sindresorhus/is · error · TypeError

Expected value which is `string with a URL`, received value

Error message

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

What it means

Thrown by `assertUrlString()` in @sindresorhus/is when the value is not a string that parses with `new URL(value)`. The underlying `isUrlString` returns false both for non-strings and for strings the WHATWG URL parser rejects — notably strings without a scheme, since `new URL()` requires an absolute URL.

Source

Thrown at source/index.ts:1969

	}
}

export function assertUrlInstance(value: unknown, message?: string): asserts value is URL {
	if (!isUrlInstance(value)) {
		throw new TypeError(message ?? typeErrorMessage('URL', value));
	}
}

// eslint-disable-next-line unicorn/prevent-abbreviations
export function assertUrlSearchParams(value: unknown, message?: string): asserts value is URLSearchParams {
	if (!isUrlSearchParams(value)) {
		throw new TypeError(message ?? typeErrorMessage('URLSearchParams', value));
	}
}

export function assertUrlString(value: unknown, message?: string): asserts value is UrlString {
	if (!isUrlString(value)) {
		throw new TypeError(message ?? typeErrorMessage('string with a URL', value));
	}
}

export function assertValidDate(value: unknown, message?: string): asserts value is Date {
	if (!isValidDate(value)) {
		throw new TypeError(message ?? typeErrorMessage('valid Date', value));
	}
}

export function assertValidLength(value: unknown, message?: string): asserts value is number {
	if (!isValidLength(value)) {
		throw new TypeError(message ?? typeErrorMessage('valid length', value));
	}
}

// eslint-disable-next-line @typescript-eslint/no-restricted-types
export function assertWeakMap<Key extends object = object, Value = unknown>(value: unknown, message?: string): asserts value is WeakMap<Key, Value> {
	if (!isWeakMap(value)) {

View on GitHub ↗ (pinned to 7821031c66)

Solutions

Ensure the string is an absolute URL with a scheme — prepend 'https://' or resolve against a base: `new URL(path, base).href`.
Check the value isn't undefined/empty — validate config/env vars at startup.
If you have a URL object, pass `url.href`, or use `assert.urlInstance` instead.

Example fix

// before
assert.urlString('example.com/api');
// after
assert.urlString('https://example.com/api');

Defensive patterns

Strategy: validation

Validate before calling

function isUrlString(value) {
  if (typeof value !== 'string') return false;
  try { new URL(value); return true; } catch { return false; }
}

Type guard

if (is.urlString(value)) {
  // value is a string containing a valid absolute URL
}

Try / catch

try {
  assert.urlString(value);
} catch (error) {
  if (error instanceof TypeError) { /* not a string or not parseable as a URL */ }
  throw error;
}

Prevention

The check requires a parseable ABSOLUTE URL — relative paths like '/foo' fail; supply a base or full URL
A URL instance fails this check (it wants a string); use is.urlInstance for objects
Trim and validate user-supplied URLs with new URL() before passing them into APIs that assert urlString

When it happens

Trigger: `assert.urlString(value)` with a relative or scheme-less string ('example.com', '/api/users'), an empty string, undefined, or a URL object (objects fail — only strings pass).

Common situations: Missing env var yielding undefined; users entering 'example.com' without 'https://'; passing path-only routes where an absolute URL is required; passing a URL instance where the string form was expected.

Related errors

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