Troubleshooting

Find solutions by problem type. Most issues leave clues in the logs.

General Approach

When something goes wrong, first check the detailed logs in ~/.ginkgo-backup/logs/, then call GET /api/v1/oversight/health to check system health. This page organizes common symptoms and solutions by problem type.

Viewing Logs

Logs are in ~/.ginkgo-backup/logs/, split by date. You can also view them via API:

Shell

# Get recent logs curl http://127.0.0.1:9275/api/v1/logs \ -H "Authorization: Bearer $TOKEN" # System health check curl http://127.0.0.1:9275/api/v1/oversight/health \ -H "Authorization: Bearer $TOKEN"

Problem Categories

Server Issues

Server won't start

  • Check if port 9275 is in use: netstat -an | grep 9275
  • Start on a different port: ./ginkgo-server --port 8080
  • Check data directory permissions: ~/.ginkgo-backup/
  • Check startup logs in ~/.ginkgo-backup/logs/

SQLITE_BUSY / database is locked errors

  • Ginkgo has built-in concurrency optimization and usually handles this automatically
  • If persistent, check for external processes accessing ginkgo.db
  • Never open the database files with external SQLite tools while the server is running

Auth token lost

  • Check ~/.ginkgo-backup/config.json for the auto-generated token
  • If lost, delete ~/.ginkgo-backup/config.json and restart the server — a new token will be generated

Backup Issues

Backup appears stuck

  • Check if the source directory contains very large files (may be hashing)
  • Check backup progress: GET /api/v1/backup/progress
  • Cancel and retry: POST /api/v1/backup/cancel

Backup uses too much memory

  • The pipeline has built-in memory limits based on system RAM
  • Reduce chunk_concurrency in source settings
  • Check for very large files that may be loaded into memory

Files not backed up

  • Check exclude patterns: GET /api/v1/sources/{id}
  • Check .ginkgo-backupignore in the source directory
  • Check backup logs: GET /api/v1/logs?source_id={id}

Restore Issues

Restore fails with decryption error

  • Ensure the correct repository is selected
  • If the key was changed, import the old key: POST /api/v1/keys/import
  • Use the recovery code: POST /api/v1/recovery-code/import

Restored files have wrong timestamps

  • Some filesystems don't support precise timestamps — this is expected
  • Check the manifest for the original mtime: GET /api/v1/snapshots/{id}

Cloud Sync Issues

Cloud sync fails

  • Test the cloud connection: POST /api/v1/cloud/test
  • Check OAuth2 token expiration (auto-refreshes, but fails if revoked)
  • Check network connectivity to the cloud endpoint
  • Check logs for specific error messages

OneDrive/Dropbox upload fails with 404

  • Parent directories must exist before uploading — Ginkgo auto-creates them
  • If the issue persists, delete and re-create the cloud backend
  • Ensure the OAuth2 app has not been revoked

Google Drive creates duplicate folders

  • Ensure the drive scope is used (not drive.file)
  • The drive.file scope prevents listing existing folders, causing duplicates
  • Delete the duplicate folders and re-authorize with the correct scope

GC Issues

GC deletes too much

  • Check if the GC safety preset was too aggressive
  • Use Normal or Paranoid preset for production
  • Always run dry_run first: POST /api/v1/retention/gc?dry_run=true
  • Check the trash directory: <repo>/.ginkgo-backup/trash/

GC doesn't run when expected

  • GC has a minimum interval (4 hours by default)
  • Check last GC run time: GET /api/v1/oversight/cleanup-logs
  • Use force: true to bypass the interval check

Mount Issues

Mount fails on Linux

  • Ensure WinFSP (Windows) or FUSE (Linux/macOS) is installed
  • Build with CGO_ENABLED=0 for FUSE support
  • Check mount point permissions

WebDAV mount disconnects

  • WebDAV sessions auto-expire after 30 minutes
  • Remount: POST /api/v1/mount/{source_id}
  • Check if the server is still running

TLS & Certificates

Browser shows certificate invalid or untrusted

  • Run ginkgo-server --tls-trust to install the local CA into the system trust store (requires admin)
  • Stale CAs with the same name are cleaned up before install to avoid conflicts
  • Ensure the CA's PermittedIPRanges covers the public IP SAN you are accessing
  • On the CLI side, use --tls or GINKGO_TLS=1 to enable HTTPS

Cannot reach the API in headless mode

  • Headless mode defaults to listening on 0.0.0.0 and auto-enables TLS
  • Make sure the firewall allows port 9275 (or your custom port)
  • Verify with https://<IP>:9275/api/v1/health (note https)
  • For public internet access, terminate TLS on a reverse proxy (Caddy/Nginx) with a public CA cert

Certificate breaks after public IP changes

  • EnsureLocalCert checks whether the existing CA's PermittedIPRanges covers the new public IP SAN
  • Update the public IP SAN in Settings and restart the service to regenerate the CA and certificate

WebUI Password & TOTP

Forgot the WebUI access password

  • On the server host, run: ginkgo-server --set-password <new-password>
  • Or edit ~/.ginkgo-backup/config.json directly to reset the password field, then restart
  • Resetting the password does not affect Token auth or existing API clients

Lost the phone used for TOTP 2FA

  • Use the backup recovery codes saved when 2FA was enabled
  • Without recovery codes, call POST /api/v1/auth/totp/disable on the server host to disable 2FA
  • After disabling, re-enable 2FA and save new recovery codes

CLI reports "certificate verification failed"

  • Make sure --tls-trust has been run to install the local CA
  • Or set GINKGO_TLS=1 so the CLI uses HTTPS
  • With a self-signed certificate and no installed CA, the CLI refuses to connect for safety

License & Activation

First launch asks for an activation code

  • Every user must enter an activation code on first launch to bind to a distributor and load branding
  • Codes are provided by your distributor; two types exist: Master Code (unlimited activations) and Paid License (100/60 per reseller pack)
  • Once bound to a distributor, you cannot switch to another distributor
  • Free-tier codes work permanently and protect up to 5 projects

Activation code invalid or exhausted

  • Contact your distributor to confirm the code's status
  • Paid license codes have a finite activation count (100 or 60 per pack)
  • Distributors purchase $1000 reseller packs via Creem to automatically open distributor accounts
  • Licenses are validated locally via ed25519 signatures; Sunset Mode keeps them working even if the company shuts down

Mesh Backup peer count is limited

  • Free tier Mesh Backup is limited to 1 peer (your computer + 1 other device)
  • Buy a Lifetime or Family license to lift the peer limit
  • License validation is local ed25519 signature verification; no internet required

Getting Help

If the above solutions don't resolve your issue:

GitHub Issues

https://github.com/ginkgo-backup/ginkgo/issues

Email Support

[email protected]

Log Location

~/.ginkgo-backup/logs/

Health Check

GET /api/v1/oversight/health

See Also

CLI ReferenceAPI ReferenceConfiguration