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

​
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, password, and database in your config
  2. Test connection manually: 
    psql -h HOST -p PORT -U USERNAME -d DATABASE
  3. Check PostgreSQL server - Ensure the server is running
  4. Network/Firewall - Verify network connectivity and firewall rules allow the connection

​
Storage Errors

​
AWS S3

1

Verify credentials

Ensure your AWS access key ID and secret access key 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
  • Verify region matches your bucket’s region
  • Ensure bucket exists and is accessible

​
Cloudflare R2

Common R2 issues and solutions
  • Verify API token - Ensure your R2 API token is correct and has not expired
  • 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 - Check cloud name, API key, and API secret are correct
  • 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'))"
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.