apify/crawlee · error · Error

The `tieredProxyUrls` option has been removed in Crawlee v4.

Error message

The `tieredProxyUrls` option has been removed in Crawlee v4. See the v4 upgrading guide for the recommended migration to named sessions.

What it means

Crawlee v4 removed the tieredProxyUrls option from ProxyConfiguration; proxies are now selected via named sessions. The constructor actively detects the legacy option and throws with a pointer to the v4 upgrading guide, so outdated code fails fast instead of silently ignoring the option.

Source

Thrown at packages/core/src/proxy_configuration.ts:118

     * const proxyConfiguration = new ProxyConfiguration({
     *     proxyUrls: ['http://user:pass@proxy-1.com', 'http://user:pass@proxy-2.com'],
     * });
     *
     * const crawler = new CheerioCrawler({
     *   // ...
     *   proxyConfiguration,
     *   requestHandler({ proxyInfo }) {
     *       const usedProxyUrl = proxyInfo.url; // Getting the proxy URL
     *   }
     * })
     *
     * ```
     */
    constructor(options: ProxyConfigurationOptions = {}) {
        const { validateRequired, ...rest } = options as Dictionary;

        if ('tieredProxyUrls' in rest) {
            throw new Error(
                'The `tieredProxyUrls` option has been removed in Crawlee v4. ' +
                    'See the v4 upgrading guide for the recommended migration to named sessions.',
            );
        }

        const { proxyUrls, newUrlFunction } = parseArgument(
            rest as ProxyConfigurationOptions,
            proxyConfigurationOptionsSchema,
        );

        if (proxyUrls && newUrlFunction) this.throwCannotCombineCustomMethods();
        if (!proxyUrls && !newUrlFunction && validateRequired) this.throwNoOptionsProvided();

        this.#proxyUrls = proxyUrls;
        this.#newUrlFunction = newUrlFunction;
    }

    /**

View on GitHub (pinned to dbe57fb09c)

Solutions

1. Remove the tieredProxyUrls option from the ProxyConfigurationOptions object.
2. Migrate to the named-sessions approach per the Crawlee v4 upgrading guide.
3. Use proxyUrls (static list) or newUrlFunction (dynamic generation) instead.
4. Pin Crawlee to v3 temporarily if you cannot migrate yet (not recommended long-term).

Example fix

// before
const proxy = new ProxyConfiguration({ tieredProxyUrls: [['http://a', 'http://b']] });
// after
const proxy = new ProxyConfiguration({ proxyUrls: ['http://a', 'http://b'] });

if ('tieredProxyUrls' in proxyOptions) {
  throw new Error('tieredProxyUrls was removed in Crawlee v4; migrate to named sessions');
}

let proxy;
try {
  proxy = new ProxyConfiguration(opts);
} catch (err) {
  if ((err as Error).message.includes('tieredProxyUrls')) {
    const { tieredProxyUrls, ...rest } = opts;
    proxy = new ProxyConfiguration(rest);
  } else throw err;
}

When it happens

Trigger: Constructing new ProxyConfiguration({ tieredProxyUrls: [...] }) or passing a configuration object that still contains tieredProxyUrls (e.g. from v3 config code or an env-parsed options object) under Crawlee v4.

Common situations: Upgrading a project from Crawlee v3 to v4 without following the migration guide; copying old ProxyConfiguration snippets; shared config files that predate v4.

Related errors

• Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}.
• The provided newUrlFunction did not return a valid URL. Caus
• Cannot combine custom proxies "options.proxyUrls" with custo
• One of "options.proxyUrls" or "options.newUrlFunction" needs
• PlaywrightCrawlerOptions.launchContext.proxyUrl is not allow

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