{
  "id": "php/laravel-queue-worker-sigterm-timeout",
  "signature": "Illuminate\\Queue\\MaxAttemptsExceededException: App\\Jobs\\SendNotification has been attempted too many times or run too long. The job may have been previously processed by a worker that was forcefully terminated.",
  "signature_zh": "Illuminate\\Queue\\MaxAttemptsExceededException：App\\Jobs\\SendNotification 已尝试次数过多或运行时间过长。该作业可能已被强制终止的工作进程处理过。",
  "regex": "Illuminate\\\\Queue\\\\MaxAttemptsExceededException: App\\\\Jobs\\\\[A-Za-z]+ has been attempted too many times or run too long",
  "domain": "php",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "A Laravel queue worker received a SIGTERM signal (e.g., during deployment or scaling) while processing a job, causing the job to be marked as failed or re-attempted without proper release, exceeding the maximum attempts limit.",
  "root_cause_type": "generic",
  "root_cause_zh": "Laravel 队列工作进程在处理作业时收到 SIGTERM 信号（例如在部署或扩展期间），导致作业被标记为失败或重新尝试而未正确释放，超过了最大尝试次数限制。",
  "versions": [
    {
      "version": "laravel 10",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "laravel 11",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "php 8.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "php 8.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "horizon 5.21",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increasing the `--tries` option on the queue worker to a very high number",
      "why_fails": "The issue is not about the number of attempts but about the job being incorrectly marked as failed due to SIGTERM; increasing tries may delay the failure but not prevent it.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disabling the `force` option in deploy scripts that send SIGTERM",
      "why_fails": "SIGTERM is necessary for graceful shutdown; disabling it can cause longer downtimes or zombie processes.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Implement a `failed` method in the job to handle the exception gracefully, and use `php artisan queue:retry all` to re-run failed jobs after ensuring workers are stable.",
      "success_rate": 0.9,
      "how": "Implement a `failed` method in the job to handle the exception gracefully, and use `php artisan queue:retry all` to re-run failed jobs after ensuring workers are stable.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Add a `pcntl_signal` handler in the job's `handle` method to catch SIGTERM and release the job back to the queue: `pcntl_signal(SIGTERM, function () { $this->release(30); });`",
      "success_rate": 0.85,
      "how": "Add a `pcntl_signal` handler in the job's `handle` method to catch SIGTERM and release the job back to the queue: `pcntl_signal(SIGTERM, function () { $this->release(30); });`",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Implement a `failed` method in the job to handle the exception gracefully, and use `php artisan queue:retry all` to re-run failed jobs after ensuring workers are stable.",
    "Add a `pcntl_signal` handler in the job's `handle` method to catch SIGTERM and release the job back to the queue: `pcntl_signal(SIGTERM, function () { $this->release(30); });`"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://laravel.com/docs/11/queues#max-attempts",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "partial",
  "first_seen": "2024-07-22",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}