Skip to main content
Run npx dbdock test to verify your configuration and diagnose issues.

​
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:
  • DBDOCK_DB_PASSWORD - Database password
  • 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 not found

If you see an error that pg_dump command is not found, you need to install PostgreSQL client tools. 
brew install postgresql

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

​
Database Connection Errors

If you’re experiencing database connection issues:
  1. Verify credentials - Check host, port, username, and database in your config
  2. Check password - Ensure DBDOCK_DB_PASSWORD is set in your .env file
  3. Test connection manually: 
    psql -h HOST -p PORT -U USERNAME -d DATABASE
  4. Check PostgreSQL server - Ensure the server is running
  5. Network/Firewall - Verify network connectivity and firewall rules allow the connection
  6. Use .pgpass - For enhanced security, consider using .pgpass instead of environment variables: 
    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.