Troubleshooting

Start with doctor. It names the failed fact, shows what it found, and prints the command or action that fixes it.

Start with doctor

Run doctor before changing config or scheduler files by hand. Fix the listed problems, then run it again. Use --json when another tool needs the same facts without terminal formatting.

$ packbat doctor

Schedule

If installed fails, run packbat init again. If live fails, run init again and inspect the scheduler. Init rewrites the expected artifact with the current Node path, Packbat entry point, and environment.

Freshness and coverage

If fresh or reconciled fails, run packbat sync. Inspect the log when freshness still fails. Claude Code removes sessions older than 30 days by default while the harness starts, so repair sync before that retention window closes.

$ packbat sync

Storage and compression

Fix read access for a listed source store, or write access for the archive root. Free at least 500 MiB when disk headroom fails. If compression fails, use the supported Node.js version, 22.16 or newer.

Off-box

If an off-box fact fails, run packbat sync and inspect the log for that destination. Confirm rclone can reach the remote with the configured mode. A failed off-box copy does not turn the plaintext archive into remote state, only encrypted objects leave the machine.

Unsupported stores

Init can report a store as found but not yet supported. That means detection worked, but Packbat has no shipped adapter for its session format. The store is not archived until support lands.

found but not yet supported