denoland/deno · error · TypeError

Invalid header name: "${name}"

Error message

Invalid header name: "${name}"

What it means

appendHeader implements the spec's header append: after normalizing the value it validates the name against HTTP token code points (checkHeaderNameForHttpTokenCodePoint). Names containing spaces, ':', empty strings, or non-ASCII characters are rejected.

Source

Thrown at ext/fetch/20_headers.js:173

  HEADER_CACHE_SIZE++;
  HEADER_NAME_CACHE[name] = valid;

  return valid;
}

/**
 * https://fetch.spec.whatwg.org/#concept-headers-append
 * @param {Headers} headers
 * @param {string} name
 * @param {string} value
 */
function appendHeader(headers, name, value) {
  // 1.
  value = normalizeHeaderValue(value);

  // 2.
  if (!checkHeaderNameForHttpTokenCodePoint(name)) {
    throw new TypeError(`Invalid header name: "${name}"`);
  }
  if (!checkForInvalidValueChars(value)) {
    throw new TypeError(`Invalid header value: "${value}"`);
  }

  // 3.
  if (headers[_guard] == "immutable") {
    throw new TypeError("Cannot change header: headers are immutable");
  }

  // 7.
  const list = headerListFromHeaders(headers);
  const lowerNames = ensureLowerNames(headers);
  const lowercaseName = byteLowerCase(name);
  for (let i = 0; i < lowerNames.length; i++) {
    if (lowerNames[i] === lowercaseName) {
      name = list[i][0];
      break;

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Use registered names with hyphens: 'Content-Type'.
2. Validate names against the token regex /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/ before set/append.
3. Never put free text into header names — only into values.

Example fix

// before
headers.set('X-Custom Name', 'v');
// after
headers.set('X-Custom-Name', 'v');

const tokenRe = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
if (!tokenRe.test(name)) {
  throw new Error(`illegal header name: ${JSON.stringify(name)}`);
}
headers.set(name, value);

function isValidHeaderName(name: string): boolean {
  return /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name);
}

try {
  headers.set(name, value);
} catch (e) {
  if (e instanceof TypeError && /Invalid header name/.test(e.message)) {
    // skip or normalize the header, log the offending name
  } else {
    throw e;
  }
}

When it happens

Trigger: headers.set('Content Type', v); headers.append('a:b', v); headers.set('', v); any name with characters outside !#$%&'*+-.^_`|~0-9A-Za-z.

Common situations: User or config data used as header names; template strings that introduce whitespace; non-ASCII (i18n) text in names.

Related errors

• Invalid header: length must be 2, but is ${header.length}
• Invalid header value: "${value}"
• ERR_HTTP_INVALID_HEADER_VALUE
• Cannot change header: headers are immutable
• Cannot change headers: headers are immutable

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/820313e829a498b7. Report an issue: GitHub.