Skip to main content
First step, always: Run npx dbdock test. It tests your database, storage, and alert config in one go.

​
Configuration Issues

​
Secrets in Config File

If you have secrets (passwords, keys) stored directly in dbdock.config.json, migrate them to environment variables: 
npx dbdock migrate-config
This command will:
  1. Extract all secrets from your config file
  2. Create/update .env with the secrets
  3. Remove secrets from dbdock.config.json
  4. Update .gitignore automatically

​
Missing Environment Variables

DBDock requires certain environment variables to be set. Ensure you have one of:
  • Database: Either DBDOCK_DB_URL or DATABASE_URL (full URL, e.g. postgresql://user:pass@host:5432/db), or DBDOCK_DB_PASSWORD with host/port/user/database in config or env (DB_HOST, DB_PORT, DB_USER, DB_NAME)
  • DBDOCK_STORAGE_ACCESS_KEY and DBDOCK_STORAGE_SECRET_KEY - For cloud storage
  • DBDOCK_ENCRYPTION_SECRET - If encryption is enabled
Check your .env file exists and contains the required variables.

​
Common Issues

​
pg_dump / pg_restore / psql not found

You need PostgreSQL client tools installed. 
brew install postgresql

sudo apt-get install postgresql-client
Download and install from PostgreSQL Downloads

​
Database connection errors

Can’t connect to database?
  1. Double-check host, port, username, password, database in config (or use DBDOCK_DB_URL / DATABASE_URL)
  2. Test manually: 
    psql -h HOST -p PORT -U USERNAME -d DATABASE
  3. Make sure the PostgreSQL server is actually running
  4. Check firewalls / security groups if it’s a remote database
  5. Use .pgpass — For enhanced security, use .pgpass instead of env vars: 
    touch ~/.pgpass
chmod 600 ~/.pgpass
echo "host:port:database:username:password" >> ~/.pgpass

​
Storage Errors

​
AWS S3

1

Verify credentials

Ensure DBDOCK_STORAGE_ACCESS_KEY and DBDOCK_STORAGE_SECRET_KEY are set in your .env file and are correct
2

Check IAM permissions

Your IAM user must have these permissions:
  • s3:PutObject - Upload backups
  • s3:GetObject - Download backups
  • s3:ListBucket - List available backups
  • s3:DeleteObject - Delete old backups
3

Verify bucket configuration

  • Check bucket name is correct in dbdock.config.json
  • Verify region matches your bucket’s region
  • Ensure bucket exists and is accessible

​
Cloudflare R2

Common R2 issues and solutions
  • Verify credentials - Ensure DBDOCK_STORAGE_ACCESS_KEY and DBDOCK_STORAGE_SECRET_KEY are set in your .env file
  • Check endpoint URL - Must be in format: https://ACCOUNT_ID.r2.cloudflarestorage.com
  • Bucket access - Ensure bucket exists and is accessible
  • Permissions - Verify R2 credentials have read/write permissions
  • Restore issues - Ensure backups are in dbdock_backups/ folder with .sql extension

​
Cloudinary

  • Verify credentials - Ensure DBDOCK_CLOUDINARY_API_KEY and DBDOCK_CLOUDINARY_API_SECRET are set in your .env file
  • Check cloud name - Verify cloud name is correct in dbdock.config.json
  • Account status - Ensure your Cloudinary account is active
  • API access - Verify API credentials have media library access permissions

​
Encryption Key Errors

Encryption keys must be exactly 64 hexadecimal characters (0-9, a-f, A-F). Generate a valid key: 
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Set the key: Store the generated key in your .env file as DBDOCK_ENCRYPTION_SECRET: 
DBDOCK_ENCRYPTION_SECRET=your-64-character-hex-key
Store your encryption key securely. If you lose it, you won’t be able to restore encrypted backups.

​
No Backups Found

If DBDock can’t find your backups:

Local Storage

  • Check files exist in configured path
  • Verify file permissions allow reading
  • Ensure files match pattern: backup-*.sql

S3/R2

  • Verify files are in dbdock_backups/ folder
  • Check bucket name and region are correct
  • Ensure files match pattern: backup-*.sql

Cloudinary

  • Check Media Library for dbdock_backups folder
  • Verify cloud name is correct
  • Ensure files match pattern: backup-*.sql

File Naming

All backups must follow the naming pattern: backup-YYYY-MM-DD-HH-MM-SS-BACKUPID.sql

​
Getting Help

DBDock provides clear, actionable error messages for most issues. If you’re still experiencing problems:
When reporting issues, include the output of npx dbdock test to help diagnose the problem faster.