Unknown enqueue strategy

Error message

Unknown enqueue strategy '${strategy satisfies never}'.

What it means

matchesEnqueueStrategy switches over known EnqueueStrategy values (same-origin, same-hostname, same-domain, regex, etc.). The default branch uses `strategy satisfies never`, so if an unknown strategy value reaches the switch at runtime (TypeScript's exhaustiveness hole — e.g. from untyped JS or an invalid string cast), it throws this error. It signals an invalid EnqueueStrategy value not covered by the library.

Solutions

Use one of the documented strategy values (same-origin, same-hostname, same-domain, regex...)
Check for typos in your strategy config (case-sensitive exact match)
Avoid `as EnqueueStrategy` casts on raw strings; validate via the union type first
If strategy comes from external config, map/normalize it to the union before enqueueing
Check library changelog if a strategy value was renamed between versions

Example fix

// before
await crawler.addRequests(requests, { strategy: 'sameHost' as EnqueueStrategy });

// after
await crawler.addRequests(requests, { strategy: 'same-hostname' });

Defensive patterns

Strategy: validation

Validate before calling

const STRATEGIES = ['same-origin', 'same-hostname', 'same-domain', 'regex'] as const;
type Strategy = typeof STRATEGIES[number];
function toStrategy(v: string): Strategy {
  if (!STRATEGIES.includes(v as Strategy)) throw new TypeError(`Unknown enqueue strategy '${v}'`);
  return v as Strategy;
}

Type guard

function isEnqueueStrategy(v: unknown): v is EnqueueStrategy {
  return typeof v === 'string' && ['same-origin', 'same-hostname', 'same-domain', 'regex'].includes(v);
}

Try / catch

try {
  await crawler.addRequests(reqs, { strategy });
} catch (err) {
  if (String(err).startsWith('Unknown enqueue strategy')) {
    log.warning(`${strategy} invalid; falling back to same-hostname`);
    await crawler.addRequests(reqs, { strategy: 'same-hostname' });
  } else throw err;
}

Prevention

Never `as EnqueueStrategy` cast raw strings; validate against the union
Centralize strategy values as constants imported from the library types
Normalize external config strings (case, kebab vs camel) before use
Check the changelog when upgrading Crawlee for strategy renames

When it happens

Trigger: Passing an EnqueueStrategy string not in the union (typo like 'sameHost' vs 'same-hostname'), constructing the strategy dynamically from config/env, or calling from plain JavaScript where types are not enforced.

Common situations: Config file or CLI flag supplying a strategy string that bypasses TypeScript checks; version change renaming strategy values; user code casting `as EnqueueStrategy` to silence the compiler with an invalid value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/53bb275d76750f62. Report an issue: GitHub.

Appendix: source

Thrown at packages/utils/src/internals/url.ts:116

        case 'same-domain': {
            const originDomain = getDomain(origin.hostname, { mixedInputs: false });

            if (originDomain) {
                return originDomain === getDomain(target.hostname, { mixedInputs: false });
            }

            // No registrable domain (e.g. an IP address), fall back to comparing origins.
            return target.origin === origin.origin;
        }
        case 'same-origin':
            // Compare scheme/host/port directly so a trailing-dot host is normalized.
            return (
                target.protocol === origin.protocol &&
                normalizeHostname(target.hostname) === normalizeHostname(origin.hostname) &&
                target.port === origin.port
            );
        default:
            throw new Error(`Unknown enqueue strategy '${strategy satisfies never}'.`);
    }
}

/**
 * Check whether `target` may be enqueued under `strategy` relative to `origin`: it must use an `http(s)`
 * scheme and match the strategy. On rejection, `reason` is a human-readable message for log output.
 */
export function filterUrl(
    target: string | URL,
    origin: string | URL,
    strategy: EnqueueStrategy | `${EnqueueStrategy}`,
): { allowed: boolean; reason?: string } {
    const targetUrl = toUrl(target);

    if (targetUrl === null || !ALLOWED_SCHEMES.has(targetUrl.protocol)) {
        return { allowed: false, reason: UNSUPPORTED_SCHEME_MESSAGE };
    }

View on GitHub (pinned to dbe57fb09c)