ruvnet/RuView · error · Exception

pg_dump failed: {error_msg}

Error message

pg_dump failed: {error_msg}

What it means

DatabaseBackup.execute_backup() shells out to pg_dump (custom format, compression 9, --no-password) and raises a generic Exception embedding pg_dump's stderr when the subprocess exits nonzero. The real cause is always in the appended stderr: common ones are authentication failure (no PGPASSWORD for the --no-password run), unreachable server, nonexistent database, or a pg_dump client version older than the PostgreSQL server (pg_dump refuses to dump newer server versions).

Source

Thrown at archive/v1/src/tasks/backup.py:169

        
        # Set environment variables
        env = os.environ.copy()
        if self.settings.db_password:
            env["PGPASSWORD"] = self.settings.db_password
        
        # Execute pg_dump
        process = await asyncio.create_subprocess_exec(
            *pg_dump_cmd,
            env=env,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE
        )
        
        stdout, stderr = await process.communicate()
        
        if process.returncode != 0:
            error_msg = stderr.decode() if stderr else "Unknown pg_dump error"
            raise Exception(f"pg_dump failed: {error_msg}")
        
        backup_size_mb = self._get_file_size_mb(backup_path)
        
        # Clean up old backups
        self._cleanup_old_backups("database_full_*.sql.gz", self.retention_days)
        
        return {
            "backup_file": backup_filename,
            "backup_path": str(backup_path),
            "backup_size_mb": backup_size_mb,
            "retention_days": self.retention_days,
        }


class ConfigurationBackup(BackupTask):
    """Backup configuration files and settings."""
    
    def __init__(self, settings: Settings):

View on GitHub (pinned to 4685618388)

Solutions

1. Read the embedded stderr in the raised message; it names the exact pg_dump failure.
2. Fix credentials/connectivity: verify with 'psql "$DATABASE_URL" -c "select 1"' using the same settings the task uses; ensure settings.db_password (PGPASSWORD) is present because --no-password forbids prompts.
3. Fix version mismatches: compare 'pg_dump --version' with the server ('SELECT version();') and install the matching or newer postgresql-client.
4. Confirm the backup directory exists and is writable, then re-run the backup task.

Example fix

# before
result = await db_backup.execute_backup(session)  # Exception: pg_dump failed: ...

# after
import subprocess
subprocess.run(['pg_dump', '--version'], check=True)  # confirm client present and version
result = await db_backup.execute_backup(session)

import shutil, subprocess
if shutil.which('pg_dump') is None:
    raise RuntimeError('pg_dump not installed on this host')
client = subprocess.run(['pg_dump', '--version'], capture_output=True, text=True).stdout

last_exc = None
for attempt in range(3):
    try:
        result = await db_backup.execute_backup(session)
        break
    except Exception as exc:
        last_exc = exc
        if 'version' in str(exc) or 'authentication' in str(exc):
            raise  # not transient: fix client version or credentials
        await asyncio.sleep(2 ** attempt * 5)
else:
    alert_ops(f'database backup failed after retries: {last_exc}')
    raise last_exc

When it happens

Trigger: Scheduled backup with wrong db_host/db_user/db_password in settings (PGPASSWORD set from settings.db_password); PostgreSQL server down or firewalled; pg_dump from OS packages older than the server major version; settings.database_url malformed; database name typo.

Common situations: Production Postgres upgraded (e.g. 14 -> 16) while the app container still has the old pg_dump client; rotated DB credentials not updated in .env; backups run from a host without network access to the DB; local dev without Postgres running.

Related errors

• tar failed: {error_msg}
• Database port must be between 1 and 65535
• Database pool size must be at least 1
• Database URL must be configured for non-development environm
• Invalid MAC address format

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/a6aac1f34793adf6. Report an issue: GitHub.