sindresorhus/is · error · TypeError

Expected value which is `whitespace string`, received value

Error message

Expected value which is `whitespace string`, received value of type `${is(value)}`.

What it means

Thrown by `assertWhitespaceString()` when the value is not a non-empty string consisting entirely of whitespace. The underlying guard is `isString(value) && /^\s+$/v.test(value)`, so it rejects non-strings, the empty string (the regex requires at least one character), and any string containing a non-whitespace character. It exists to distinguish 'blank but not empty' strings — a different condition from `isEmptyString` or the combined `isEmptyStringOrWhitespace`.

Source

Thrown at source/index.ts:2008

}

// eslint-disable-next-line @typescript-eslint/no-restricted-types
export function assertWeakRef<T extends object = object>(value: unknown, message?: string): asserts value is WeakRef<T> {
	if (!isWeakRef(value)) {
		throw new TypeError(message ?? typeErrorMessage('WeakRef', value));
	}
}

// eslint-disable-next-line @typescript-eslint/no-restricted-types
export function assertWeakSet<T extends object = object>(value: unknown, message?: string): asserts value is WeakSet<T> {
	if (!isWeakSet(value)) {
		throw new TypeError(message ?? typeErrorMessage('WeakSet', value));
	}
}

export function assertWhitespaceString(value: unknown, message?: string): asserts value is string {
	if (!isWhitespaceString(value)) {
		throw new TypeError(message ?? typeErrorMessage('whitespace string', value));
	}
}

export default is;

export type {
	ArrayLike,
	Class,
	EvenInteger,
	FiniteNumber,
	Integer,
	NaN,
	NegativeInfinity,
	NegativeInteger,
	NegativeNumber,
	NodeStream,
	NonNegativeInteger,
	NonNegativeNumber,

View on GitHub ↗ (pinned to 7821031c66)

Solutions

If empty strings should also pass, use `assertEmptyStringOrWhitespace` instead — that is the guard meaning 'blank'.
Ensure the value is a string before asserting; coerce or validate upstream if it may be a number, null, or undefined.
Don't trim before the assertion — `value.trim()` turns a whitespace string into an empty one, which fails.
If you actually want 'has meaningful content', invert with `assertNonEmptyStringAndNotWhitespace` rather than negating this assertion.

Example fix

// before
assertWhitespaceString(''); // throws — empty string is not whitespace

// after
assertEmptyStringOrWhitespace(''); // passes: covers both empty and whitespace-only

Defensive patterns

Strategy: validation

Validate before calling

const isWhitespaceString = (value: unknown): boolean =>
  typeof value === 'string' && value.length > 0 && /^\s+$/.test(value);

if (isWhitespaceString(value)) {
  assert.whitespaceString(value); // safe
}

Type guard

import is from '@sindresorhus/is';

function ensureWhitespaceString(value: unknown): string | undefined {
  return is.whitespaceString(value) ? value : undefined;
}

Try / catch

try {
  assert.whitespaceString(value);
} catch (error) {
  if (error instanceof TypeError) {
    // value was not a whitespace-only string
    handleInvalidInput(error.message);
  } else {
    throw error;
  }
}

Prevention

Note the assertion requires a NON-EMPTY string consisting entirely of whitespace — the empty string '' fails it; check value.length > 0 first
Do not assume trimmed input passes: any visible character makes the string non-whitespace
If you actually want 'empty or whitespace' semantics, use is.emptyStringOrWhitespace instead of this stricter check
Guard with is.whitespaceString(value) before asserting when the string comes from user input or external data

When it happens

Trigger: Calling `assertWhitespaceString(value)` (or `is.assert.whitespaceString(value)`) with a non-string, with `''` (empty fails the `+` quantifier), or with a string containing any visible character, e.g. `' a '`. Only strings like `' '`, `'\t\n'` pass. Note the regex uses the `v` flag, which requires Node.js 20+/modern engines — on older runtimes the failure would be a SyntaxError at load, not this TypeError.

Common situations: Usually hit in input-sanitization or linting-style code that checks whether user input is blank: developers expect `''` to count as whitespace, but this assertion deliberately excludes the empty string. Also hit when trimmed input is passed (trimming removes the whitespace, yielding `''`).

Related errors

AI-assisted analysis of sindresorhus/is@7821031c66 (2026-07-31). Data as JSON: /data/errors/b41fd4735bd9f4a4.json. Report an issue: GitHub ↗.