apify/crawlee · error · Error

`alwaysEnqueue` cannot be used together with a custom `uniqu

Error message

`alwaysEnqueue` cannot be used together with a custom `uniqueKey`.

What it means

A custom uniqueKey deduplicates the request by that key, while alwaysEnqueue forces the request to be enqueued regardless of deduplication — the two are contradictory, so the Request constructor throws when both are provided.

Source

Thrown at packages/core/src/request.ts:220

            skipNavigation,
            enqueueStrategy,
            crawlDepth,
        } = options as RequestOptions & {
            loadedUrl?: string;
            retryCount?: number;
            sessionId?: string;
            errorMessages?: string[];
            handledAt?: string | Date;
        };

        let { method = 'GET' } = options;

        method = method.toUpperCase() as AllowedHttpMethods;

        if (method === 'GET' && payload) throw new Error('Request with GET method cannot have a payload.');

        if (uniqueKey && alwaysEnqueue) {
            throw new Error('`alwaysEnqueue` cannot be used together with a custom `uniqueKey`.');
        }

        this.id = id;
        this.url = url;
        this.loadedUrl = loadedUrl;
        this.uniqueKey =
            uniqueKey ||
            CrawleeRequest.computeUniqueKey({
                url,
                method,
                payload,
                keepUrlFragment,
                useExtendedUniqueKey,
                alwaysEnqueue,
            });
        this.method = method;
        this.payload = payload;
        this.noRetry = noRetry;

View on GitHub (pinned to dbe57fb09c)

Solutions

Remove alwaysEnqueue if you want deduplication via uniqueKey
Remove uniqueKey if you truly want every occurrence enqueued
Generate uniqueKey per occurrence (e.g. include a nonce) instead of using alwaysEnqueue

Example fix

// before
new Request({ url, uniqueKey: 'item-1', alwaysEnqueue: true });
// after
new Request({ url, uniqueKey: 'item-1' });

Defensive patterns

Strategy: validation

Validate before calling

if (opts.uniqueKey && opts.alwaysEnqueue) throw new Error('uniqueKey and alwaysEnqueue are mutually exclusive');

Try / catch

try {
  return new Request(opts);
} catch (err) {
  if (err.message.includes('alwaysEnqueue')) {
    const { alwaysEnqueue, ...rest } = opts;
    return new Request(rest);
  }
  throw err;
}

Prevention

Decide per request: dedup via uniqueKey OR force-enqueue, never both
Document the mutual exclusivity in request factory helpers
Review global alwaysEnqueue flags that conflict with keyed requests

When it happens

Trigger: new Request({ url, uniqueKey: 'my-key', alwaysEnqueue: true }).

Common situations: Copy-pasting options from different call sites; enabling alwaysEnqueue globally for retries while requests also carry uniqueKeys; misunderstanding that uniqueKey already controls dedup behavior.

Related errors

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