Troubleshooting

Troubleshooting

Integration cannot be found

1. Confirm /config/custom_components/backup_checkup/manifest.json exists.
2. Remove any accidental extra directory level from the release archive.
3. Restart Home Assistant completely.
4. Clear the browser cache if necessary and search again under Add integration.
5. Confirm Home Assistant 2026.3.0 or newer is installed.

Panel is black or missing

1. Confirm Show sidebar panel is enabled.
2. Restart Home Assistant after the update.
3. Reload the browser with Ctrl+F5 or clear the Companion App cache.
4. For manual installs, replace the complete integration directory.
5. In browser network tools, confirm the versioned backup-checkup-panel module returns HTTP 200.

For 3.0.12, the working module URL ends in backup-checkup-panel-3.0.12-r1.js and defines backup-checkup-panel-v3-0-12-r1. If a 3.0.11 module is still shown, replace the complete integration directory, restart Home Assistant, and reload the browser or Companion App.

The integration continues monitoring even if the panel fails to render.

No backups or backup manager unavailable

Open Home Assistant's native backup page. If it also has no data, the issue is outside BackupCheckup. Check the Backup integration, Supervisor, and storage agents, then restart Home Assistant if the manager remains unavailable.

Backup is reported as stale

Age uses complete 24-hour periods. Inspect the exact timestamp in attributes or an Expert timestamp sensor. A newer complete manual backup can temporarily cover an overdue automatic backup, while schedule problems remain visible separately.

Redundancy warning despite multiple backups

Redundancy applies to copies of the newest regular backup, not arbitrary old files. Confirm the same newest backup is present on the required number of reachable agents.

Suspicious backup size

Automatic checking compares only backups with matching origin and scope. Check whether contents were removed or whether a technical app-update snapshot is involved. In fixed mode, verify the configured minimum.

Integrity states

password_required

Home Assistant could not supply the correct password. Check the Emergency Kit or backup password in native backup settings. BackupCheckup does not store a separate password.

corrupt

Metadata, an outer or inner archive, a file, or the SQLite check failed. Keep the file for diagnosis, check a copy from another location, create and verify a new backup, and do not rely on the failed file as the only recovery point.

unreadable

Download or opening failed. Check reachability, permissions, free temporary storage, and the native storage agent. This result does not necessarily prove archive corruption.

valid_with_warnings

All archives were readable, but a non-blocking inconsistency was detected. Inspect the fixed warning codes in attributes or sanitized diagnostics.

aborted

A safety boundary stopped the check. Common codes:

• download_size_limit: confirm expected size, then increase the download limit if justified,
• expanded_size_limit: investigate unexpected expansion,
• archive_member_limit or metadata_size_limit: investigate unusual archive structure and create a new backup,
• insufficient_free_space: free temporary storage or disable database verification,
• verification_timeout or database_timeout: check storage performance and load, then deliberately raise the timeout.

An aborted result does not prove corruption.

Manual check is unavailable

Only administrators can start it. A regular backup must exist, no other check may be running, and the configured cooldown must have expired.

Database verification fails

Create and verify a new backup, then investigate Recorder and production database health. The check runs against a temporary copy and cannot damage the original database.

Temporary data could not be removed

BackupCheckup creates a Repair. Check filesystem permissions and disk errors, then restart Home Assistant. Startup cleanup removes only old, unambiguously named BackupCheckup temporary directories.

Notification test button is unavailable

Enable mobile notifications and select at least one enabled Companion App notify entity. Disabled, removed, or unrelated notification services are rejected.

Runner is not detected

1. Confirm Home Assistant OS is used.
2. Start the app and open its log.
3. Look for discovery registered.
4. Confirm integration and runner support the same protocol.
5. Reload the integration or restart Home Assistant.

Runner test fails

Check the version line first. A HACS update does not update the app. The log must show the expected runner version.

Stable codes include:

• home_assistant_memory_limit: virtual address-space limit reached,
• home_assistant_file_limit: file-size boundary reached,
• home_assistant_permission_denied: the temporary configuration or runtime log is not accessible; runner 3.0.11 and newer prepare the runtime log for the unprivileged sandbox user. Refresh the App Store, rebuild or reinstall the current runner, and confirm runner initialized version=3.0.12 in its log,
• home_assistant_runtime_missing: Home Assistant Python module missing from the image,
• home_assistant_cli_incompatible: unsupported startup option,
• home_assistant_start_timeout: instance did not become ready,
• home_assistant_exited: another early process exit,
• sandbox_preflight_failed: privilege separation could not be confirmed.

Increase app limits only when backup size and host resources justify it.

Unexpected Health Score

Inspect sensor.backup_checkup_health_score attributes. raw_deductions shows every signal, deductions the applied values, and suppressed_correlated_deductions symptoms not counted twice.

Debug logging

Temporarily add:

logger:
  default: info
  logs:
    custom_components.backup_checkup: debug

Restart, reproduce the issue, and remove debug logging afterward.

Preparing a bug report

Include BackupCheckup version, Home Assistant version, installation type, exact steps, relevant sanitized logs, and diagnostics. Never publish backups, passwords, Emergency Kit data, or unredacted configuration.