Troubleshooting

Troubleshooting

Start by collecting version, install path, logs, and health output.

convex-autobackup --version
convex-autobackup doctor --json
curl http://localhost:8976/api/v1/health

Docker container does not start

Check logs:

docker logs convex-autobackup

Check container state:

docker ps -a
docker inspect convex-autobackup

Common causes:

• Missing or invalid CONVEX_AUTOBACKUP_MASTER_KEY.
• /data volume is not writable.
• Port 8976 is already in use.
• Host cannot download the managed Convex runner.

Web UI is not reachable

Confirm the app is listening:

curl http://localhost:8976/api/v1/health

Confirm Docker port mapping:

docker ps

If remote:

• Check firewall rules.
• Check reverse proxy config.
• Confirm DNS points at the right host.
• Confirm HTTPS certs are valid.

Login or bootstrap problems

Bootstrap is only available before the first user exists. After owner creation, use normal login or owner/admin user management.

If you lost owner access, stop and inspect your data backup plan before changing the database manually.

Convex export fails

Check:

• Deploy key is valid.
• Deployment name exactly matches the intended Convex deployment.
• Deploy key can access the project.
• Host can reach Convex services.
• Managed runner is installed:

convex-autobackup runner install --json
convex-autobackup doctor --json

Backup succeeds but verification fails

Possible causes:

• Destination write was interrupted.
• Object storage returned stale or partial data.
• Local disk corruption or manual file changes.
• Manifest/archive pair no longer match.

Do not delete the failed artifact until you understand whether it is the only copy for that time window.

Restore is blocked

Restore requires exact deployment confirmation:

convex-autobackup restore \
  --run-id <run-id> \
  --target-id <target-id> \
  --confirm-deployment <deployment-name> \
  --json

Use the deployment name shown in the target. This guard is intentional.

Cargo install fails

Update Rust:

rustup update stable
cargo install convex-autobackup --version 0.1.0-beta.1

If the release was just published, crates.io indexing may take a few minutes.

Release asset missing

Check the release workflow:

https://github.com/KodyDennon/ConvexAutoBackup/actions/workflows/release.yml

Then check the release:

https://github.com/KodyDennon/ConvexAutoBackup/releases/latest

If one channel published but another failed, the workflow is designed so reruns can skip already-published crates at the same version.

More docs

• README: https://github.com/KodyDennon/ConvexAutoBackup#readme
• Deployment docs: https://github.com/KodyDennon/ConvexAutoBackup/blob/main/docs/DEPLOYMENT.md
• Open source release docs: https://github.com/KodyDennon/ConvexAutoBackup/blob/main/docs/OPEN_SOURCE_RELEASE.md