node-fetch/node-fetch · error · TypeError

Failed to construct 'Headers': The provided value is not of

Error message

Failed to construct 'Headers': The provided value is not of type '(sequence<sequence<ByteString>> or record<ByteString, ByteString>)'

What it means

TypeError thrown at the end of the Headers constructor (src/headers.js:93) when init is neither null/undefined, nor a non-iterable object (Record), nor an iterable object. This is the catch-all for primitives — strings, numbers, booleans, BigInt, and boxed primitives (via types.isBoxedPrimitive) — which cannot be coerced into either of the two HeadersInit overloads.

Source

Thrown at src/headers.js:93

				result = [...init]
					.map(pair => {
						if (
							typeof pair !== 'object' || types.isBoxedPrimitive(pair)
						) {
							throw new TypeError('Each header pair must be an iterable object');
						}

						return [...pair];
					}).map(pair => {
						if (pair.length !== 2) {
							throw new TypeError('Each header pair must be a name/value tuple');
						}

						return [...pair];
					});
			}
		} else {
			throw new TypeError('Failed to construct \'Headers\': The provided value is not of type \'(sequence<sequence<ByteString>> or record<ByteString, ByteString>)');
		}

		// Validate and lowercase
		result =
			result.length > 0 ?
				result.map(([name, value]) => {
					validateHeaderName(name);
					validateHeaderValue(name, String(value));
					return [String(name).toLowerCase(), String(value)];
				}) :
				undefined;

		super(result);

		// Returning a Proxy that will lowercase key names, validate parameters and sort keys
		// eslint-disable-next-line no-constructor-return
		return new Proxy(this, {
			get(target, p, receiver) {

View on GitHub (pinned to 8b3320d2a7)

Solutions

Pass an object literal: { 'Content-Type': 'application/json' }
Parse raw header strings into [name, value] pairs first
Default headers to {} instead of '' or undefined-typed primitives when none provided
Add a typeof init === 'object' guard in your own header-builder helper

Example fix

// before
new Headers('Content-Type: application/json'); // throws

// after
new Headers({ 'Content-Type': 'application/json' });

Defensive patterns

Strategy: type-guard

Validate before calling

// Coerce primitives to objects
function coerceHeaders(init) {
  if (init == null || typeof init !== 'object') return {};
  return init;
}

Type guard

function isObjectHeadersInit(init) {
  return init == null || (typeof init === 'object' && !['string','number','boolean','bigint','symbol'].includes(typeof init));
}

Try / catch

try {
  new Headers(init);
} catch (e) {
  if (/not of type/.test(e.message)) {
    new Headers({}); // fall back to empty headers
  }
}

Prevention

Always pass object literals or arrays to the Headers constructor
Default optional headers to {} instead of undefined-primitive or ''
Parse raw 'Name: Value' strings into pairs before construction

When it happens

Trigger: Passing a string like 'Content-Type: application/json'; a number, boolean, or BigInt as headers; a Symbol; boxed primitives like new Number(1); null being valid but other primitives not.

Common situations: Loading a raw header string from config without parsing; serialization round-trips that produced a primitive; user input that wasn't coerced to an object; misconfigured defaults where headers fall back to a primitive.

Related errors

AI-assisted analysis of node-fetch/node-fetch@8b3320d2a7 (2026-08-03). Data as JSON: /data/errors/b171de3277aae254.json. Report an issue: GitHub.