Skip to content

Troubleshooting

Jump to bottom
Kody Dennon edited this page Jul 4, 2026 · 3 revisions

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.

Web UI crashes after loading

If the browser console shows a GitHub /releases/latest 404 or Cannot read properties of undefined, install v0.1.0-beta.5 or newer. Beta-only GitHub projects do not always have a stable "latest" release, and older web builds did not guard every partial API response before rendering the dashboard.

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, create another owner from the same server shell instead of editing the database manually:

convex-autobackup user create \
  --email owner@example.com \
  --password "change-this-strong-password" \
  --role owner \
  --json

Then sign in through the web UI with that owner account. Keep the generated password in your normal secrets manager.

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.5

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/tag/v0.1.0-beta.5

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

More docs

ConvexAutoBackup docs: Repository · Releases · Docker Hub · crates.io

ConvexAutoBackup

Project

Clone this wiki locally