{
  "id": "nextjs/middleware-response-header-override",
  "signature": "Error: Middleware set header 'X' after response headers were already sent.",
  "signature_zh": "错误：中间件在响应头已发送后设置了标头 'X'。",
  "regex": "Error: Middleware set header '.*' after response headers were already sent\\.",
  "domain": "nextjs",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "The middleware function attempts to modify response headers (e.g., via response.headers.set()) after the response has already been sent or after calling NextResponse.next() without properly cloning the response.",
  "root_cause_type": "generic",
  "root_cause_zh": "中间件函数在响应已发送或调用 NextResponse.next() 后尝试修改响应头（例如，通过 response.headers.set()），而没有正确克隆响应。",
  "versions": [
    {
      "version": "Next.js 13.5",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Next.js 14.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Next.js 14.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Next.js 15.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "response.headers.set() is synchronous; adding await does not change the timing. The header is still set after the response is sent.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The response is already sent by the time the timeout executes, and headers cannot be modified after the fact. This also introduces race conditions.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Both set() and append() modify the same header object; the error is about timing, not the method used. The response is already sent.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Set headers before calling NextResponse.next() or before sending the response. Use NextResponse.rewrite() or NextResponse.redirect() with headers in the constructor.",
      "success_rate": 0.9,
      "how": "Set headers before calling NextResponse.next() or before sending the response. Use NextResponse.rewrite() or NextResponse.redirect() with headers in the constructor.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use the 'request' object to read headers and set them on a new response. Avoid modifying the original response after it's used.",
      "success_rate": 0.85,
      "how": "Use the 'request' object to read headers and set them on a new response. Avoid modifying the original response after it's used.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If you need to set headers conditionally, create a new NextResponse object instead of mutating the one from NextResponse.next().",
      "success_rate": 0.8,
      "how": "If you need to set headers conditionally, create a new NextResponse object instead of mutating the one from NextResponse.next().",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "在调用 NextResponse.next() 或发送响应之前设置标头。使用带有标头的 NextResponse.rewrite() 或 NextResponse.redirect() 在构造函数中设置。",
    "使用 'request' 对象读取标头并在新响应上设置。避免在原始响应被使用后修改它。",
    "如果需要有条件地设置标头，创建一个新的 NextResponse 对象，而不是修改 NextResponse.next() 返回的对象。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://nextjs.org/docs/app/building-your-application/routing/middleware",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.83,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-02-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}