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​

404 — Route POST:/auth/nonce not found on server​

You tried to authenticate with SIWE (wallet / private-key signature) against the production API, but the SIWE nonce handshake returned 404.

Fix: use a portal-minted API key instead — it is the supported and simplest path for automation. Generate one in the portal (API Keys) and pass it as APIKey to NewBackupClient. You do not call Authenticate() with an API key.

client, _ := sdkclient.NewBackupClient(sdkclient.BackupClientOptions{
    APIURL:      "https://baas-api.lighthouse.storage",
    APIKey:      os.Getenv("LH_API_KEY"),
    WorkspaceID: os.Getenv("LH_WORKSPACE_ID"),
})

not authenticated …​

No credential was set. Pass APIKey (or Token) to NewBackupClient, or call 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 upload was rejected even though the workspace appears to have free space (e.g. only a few MB used against a multi-GB limit). This can happen when a workspace's allocation is capped or stuck.

Fixes, in order:

  1. Prune old snapshots to free space and retry — see prune (or set LH_KEEP_LATEST in the automated job).

  2. If the error persists on that workspace, create a fresh workspace (it starts at 0 bytes used) and point your job at it by updating LH_WORKSPACE_ID.

    ws, _ := client.CreateWorkspace(sdktypes.WorkspaceCreateRequest{Name: "cms-backups"})
    client.SetWorkspaceID(ws.WorkspaceID)

    Then export the new UUID for the scheduled job: export LH_WORKSPACE_ID="<new-uuid>".

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 returns an APIKeyCreateResponse. The prefix lives on the nested 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.