Skip to main content

Troubleshooting

Common errors when setting up automated backups, and how to resolve them. These are drawn from real deployments (e.g. backing up a Strapi SQLite database to a scheduled job).

Authentication​

not authenticated …​

No credential was set. Pass an API key (Go: APIKey, JS: apiKey) — or a Token / token — when constructing the client, or call SetAPIKey / setAPIKey.

401 — token rejected​

The key was revoked or expired. Create a new one in the portal (keys are immutable; you cannot edit an existing one).

403 — insufficient scope​

The API key lacks a required scope. Mint a new key with the missing scope — see the scope cheat-sheet. Keys cannot be re-scoped after creation.

Storage & quota​

413 — Storage limit exceeded​

The workspace has reached its storage limit. Check current usage against the limit on the Workspaces page in the portal.

Fixes:

  1. Prune old snapshots to free space and retry — see prune (or set LH_KEEP_LATEST in the automated job).
  2. Upgrade the workspace for more capacity — see pricing.

If you receive this error while the portal shows the workspace well under its limit, that is not expected — contact mail@lighthouse.storage with your workspace ID rather than working around it, so we can correct the accounting.

Build & environment​

command 'go' not found (in cron / systemd / CI)​

You installed Go from the tarball into /usr/local/go, but non-interactive shells (cron jobs, systemd services, CI runners) do not load ~/.bashrc, so your PATH export is missing.

Fixes:

  • Call the Go toolchain by its absolute path when building: /usr/local/go/bin/go build -o /root/bin/lh-backup .
  • Better: build the uploader once into a static binary and have the scheduler run that binary by absolute path (/root/bin/lh-backup) — no Go needed at runtime.
  • If a unit really must find go, set Environment=PATH=/usr/local/go/bin:/usr/bin:/bin in the systemd service.

keyResp.KeyPrefix undefined (type types.APIKeyCreateResponse has no field or method KeyPrefix)​

CreateAPIKey / createAPIKey returns an APIKeyCreateResponse. The prefix lives on the nested APIKey / apiKey, not the top-level response.

keyResp, _ := client.CreateAPIKey(req)

plain  := keyResp.Plaintext()        // the raw lh_… key — store now, shown once
prefix := keyResp.APIKey.KeyPrefix   // the prefix (safe to log)
id     := keyResp.APIKey.APIKeyID

Backup behavior​

Backup re-uploads everything each run​

The target's .lighthouse/source_id file was deleted or changed, so the dedup/source history was lost. Preserve that file (and the .lighthouse directory) between runs so incremental backups line up under one Backup Source.

Connection / DNS errors​

Check that APIURL is the API host https://baas-api.lighthouse.storage — not the portal host baas.lighthouse.storage.

SQLite-specific​

Backup file is corrupt or locked​

Don't copy data.db with cp while the app is running. Use SQLite's online backup, which is safe against concurrent writers:

sqlite3 /path/to/app.db ".backup './db-dumps/app.sqlite'"

See Back up SQLite.