n8n Custom Header Errors

Step by Step Guide to solve n8n Custom Header Errors

 

 

---

 

Who this is for: n8n workflow designers who receive “Missing or malformed header” errors from HTTP Request nodes and need a reliable, production‑ready fix. We cover this in detail in the n8n API Integration Errors Guide.

Quick Diagnosis

Problem – HTTP Request nodes reject calls with Missing or malformed header errors.

30‑second fix

1. Open the HTTP Request node → Headers tab.
2. Add the required header name (e.g., Authorization).
3. Set its value with an Expression that guarantees a string, e.g. {{ String($json["token"]).trim() }}.
4. Save → Run the workflow.

Result – The request succeeds; the error disappears.

1. Why n8n Throws “Custom Header Error”

If you encounter any n8n oauth2 token refresh errors resolve them before continuing with the setup.

Symptom	Typical Cause	n8n Diagnostic Message
Missing Header	Header key not defined or expression returns null/undefined	Error: Request failed – Missing required header: X‑My‑Header
Malformed Header	Value is not a plain string (object, array, number) or contains illegal characters (\n, \r)	Error: Header value for X‑My‑Header is not a valid string
Encoding Issue	UTF‑8 characters not URL‑encoded when required	Error: Header value contains unsupported characters

Explanation: n8n validates each header before sending the request. If a header is absent or its value fails the internal typeof value === "string" check, the node aborts with the messages above.

2. Step‑by‑Step Diagnosis

If you encounter any n8n credential rotation errors resolve them before continuing with the setup.

Micro‑summary – Use the built‑in debugger to see exactly what value n8n is trying to send.

1. Enable Debug Mode
   Gear ⚙️ → Settings → Execution Mode → “Run Once (Debug)”.
2. Inspect the Headers in the Execution Log
   Expand the failing HTTP Request node.
   Red badges highlight offending headers; hover to view the raw value (null, [object Object], etc.).
3. Trace the Source
   Identify the upstream node that supplies the header (e.g., Set, Function, Webhook).
   Verify that node’s output in the same log.
4. Validate Types in the Expression Editor
   Enter {{$json["myValue"]}} → the preview must be a plain string.
   If it shows object, wrap with String() or JSON.stringify().

3. Fixing Missing Headers

3.1 Add a Static Header

Context: Use when the header value never changes (API key, static token).

{
  "headerParametersUi": {
    "parameter": [
      {
        "name": "X-Api-Key",
        "value": "YOUR_STATIC_KEY"
      }
    ]
  }
}

3.2 Add a Dynamic Header from Workflow Data

Context: Pull a token or other value from a previous node.

1. Set node – expose the token

{
  "values": [
    {
      "name": "token",
      "value": "{{$json[\"access_token\"]}}"
    }
  ]
}

2. Reference it in the HTTP Request node (Headers tab → Expression)

{{ $json["token"] }}

3. Force string conversion (EEFA) – protects against numbers, booleans, or null.

{{ String($json["token"]).trim() }}

4. Fixing Malformed Headers

Issue	Root Cause	Remedy
Non‑string value	Expression returns object/array	{{ JSON.stringify($json["payload"]) }} or {{ String($json["value"]) }}
Trailing newline (\n/\r)	Copied from a file or env var with line break	{{ $json["rawToken"].trim() }}
Invalid characters (spaces, quotes)	Token contains whitespace	{{ encodeURIComponent($json["token"]) }}
Binary data (Buffer)	Directly passing a Buffer object	{{ $json["file"].toString('base64') }}

Example: Clean Up a Token with Whitespace

{{ $json["rawToken"].trim() }}

Example: Encode a URL‑Sensitive Header

{{ encodeURIComponent($json["callbackUrl"]) }}

5. Advanced: Dynamic Header Generation with Expressions

Context: Build composite headers such as Bearer <token> in a single expression.

{{ `Bearer ${String($json["accessToken"]).trim()}` }}

Why it works

• Template literal (` `) guarantees a string result.
• String() forces the token to a string type, eliminating type‑mismatch errors.
• .trim() removes hidden newline characters that often trigger “malformed header” failures.

6. Testing Outside n8n (Postman / curl)

Tool	Command	Expected Result
curl	curl -H “X-Api-Key: $API_KEY” https://api.example.com/v1/resource	200 OK if header is correct
Postman	Add header → Key: X-Api-Key, Value: {{apiKey}} (environment variable)	Same as curl
n8n	Run workflow in Debug mode	No “Custom Header Error” in log

*If external tools succeed but n8n still fails, the problem lies in the node’s data handling (type conversion, whitespace, etc.).*

7. Production‑Grade EEFA Checklist

• Never store secrets in plain text – use n8n Credentials ({{ $credentials.apiKey }}) and reference them securely.
• Mask sensitive headers in logs: enable “Hide Sensitive Data” in workflow settings.
• Rate‑limit awareness – malformed‑header rejections can trigger IP throttling; verify header correctness before scaling.
• Retry logic – add a Retry node or enable “Continue On Fail” with exponential back‑off to prevent cascade failures.
• Audit header length – HTTP spec limits a header line to 8 KB; oversized custom headers may be silently dropped.

8. Frequently Asked Questions

Q1. My header value must be a JSON object. Why does n8n still complain?

Answer: n8n expects a string. Convert the object: {{ JSON.stringify($json["payload"]) }}.

Q2. Can I set headers globally for all HTTP Request nodes?

Answer: Not directly. Use Workflow Settings → “Default Request Headers” (available from v0.225) or create a reusable “Header Builder” sub‑workflow that returns a header map.

Q3. The API says the header is optional, but n8n throws an error when I omit it.

Answer: Some APIs still require a placeholder. Add an empty string to satisfy n8n’s validation: {{ "" }}.

Conclusion

Key takeaways

1. n8n validates every header as a plain string before sending the request.
2. The most common failure modes are missing keys, non‑string values, and stray whitespace or illegal characters.
3. Resolve them by:
   • Defining the header explicitly in the node UI.
   • Using concise expressions that enforce String() conversion and .trim().
   • Applying encodeURIComponent() or JSON.stringify() when the API expects encoded or JSON payloads.
4. Verify the fix with n8n’s debug mode and, if needed, with external tools (curl/Postman).

By following the EEFA checklist and the patterns above, your HTTP Request nodes will send well‑formed headers reliably, keeping your production workflows stable and secure.