{
  "id": "database/postgresql-wal-archive-timeout",
  "signature": "ERROR: archive command failed with exit code 1",
  "signature_zh": "错误：归档命令失败，退出码为 1",
  "regex": "ERROR: archive command failed with exit code \\d+",
  "domain": "database",
  "category": "system_error",
  "subcategory": null,
  "root_cause": "The PostgreSQL archive_command (e.g., cp or rsync) failed due to disk full, permission issues, or network unreachability, causing WAL archiving to stall and potentially leading to replication lag or transaction loss.",
  "root_cause_type": "generic",
  "root_cause_zh": "PostgreSQL 的 archive_command（例如 cp 或 rsync）因磁盘空间不足、权限问题或网络不可达而失败，导致 WAL 归档停滞，可能引发复制延迟或事务丢失。",
  "versions": [
    {
      "version": "PostgreSQL 15.6",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PostgreSQL 14.11",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PostgreSQL 16.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increasing archive_timeout to reduce archiving frequency",
      "why_fails": "This only delays the failure; the archive command will still fail if the underlying issue (e.g., disk space) is not resolved.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Setting archive_mode = off to stop archiving entirely",
      "why_fails": "This disables WAL archiving, which may be required for PITR or replication; it also leaves the system without a backup strategy, risking data loss.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Restarting PostgreSQL without fixing the archive destination",
      "why_fails": "Restarting does not resolve the root cause; the archive command will fail again immediately after the restart.",
      "fail_rate": 1.0,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Check the archive destination for disk space (df -h /archive/path) and permissions (ls -ld /archive/path). If full, free space or move to a different location; then update archive_command in postgresql.conf and reload: SELECT pg_reload_conf();",
      "success_rate": 0.9,
      "how": "Check the archive destination for disk space (df -h /archive/path) and permissions (ls -ld /archive/path). If full, free space or move to a different location; then update archive_command in postgresql.conf and reload: SELECT pg_reload_conf();",
      "condition": "",
      "sources": []
    },
    {
      "action": "Test the archive command manually: su - postgres -c 'archive_command_test' (e.g., cp /path/to/test.wal /archive/). If it fails, fix the command (e.g., add -p to mkdir) or switch to a simpler method like pg_receivewal.",
      "success_rate": 0.85,
      "how": "Test the archive command manually: su - postgres -c 'archive_command_test' (e.g., cp /path/to/test.wal /archive/). If it fails, fix the command (e.g., add -p to mkdir) or switch to a simpler method like pg_receivewal.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If the archive destination is temporarily unavailable, set archive_mode = off in postgresql.conf and restart, then re-enable it after fixing the destination: ALTER SYSTEM SET archive_mode = off; SELECT pg_reload_conf(); -- then fix destination, then set archive_mode = on.",
      "success_rate": 0.8,
      "how": "If the archive destination is temporarily unavailable, set archive_mode = off in postgresql.conf and restart, then re-enable it after fixing the destination: ALTER SYSTEM SET archive_mode = off; SELECT pg_reload_conf(); -- then fix destination, then set archive_mode = on.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Check the archive destination for disk space (df -h /archive/path) and permissions (ls -ld /archive/path). If full, free space or move to a different location; then update archive_command in postgresql.conf and reload: SELECT pg_reload_conf();",
    "Test the archive command manually: su - postgres -c 'archive_command_test' (e.g., cp /path/to/test.wal /archive/). If it fails, fix the command (e.g., add -p to mkdir) or switch to a simpler method like pg_receivewal.",
    "If the archive destination is temporarily unavailable, set archive_mode = off in postgresql.conf and restart, then re-enable it after fixing the destination: ALTER SYSTEM SET archive_mode = off; SELECT pg_reload_conf(); -- then fix destination, then set archive_mode = on."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://www.postgresql.org/docs/16/continuous-archiving.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-02-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}