{"record":{"id":"a769403c009316a1","repo":"apify/crawlee","slug":"the-tieredproxyurls-option-has-been-removed-in-c","errorCode":null,"errorMessage":"The `tieredProxyUrls` option has been removed in Crawlee v4. See the v4 upgrading guide for the recommended migration to named sessions.","messagePattern":"The `tieredProxyUrls` option has been removed in Crawlee v4\\. See the v4 upgrading guide for the recommended migration to named sessions\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/proxy_configuration.ts","lineNumber":118,"sourceCode":"     * const proxyConfiguration = new ProxyConfiguration({\n     *     proxyUrls: ['http://user:pass@proxy-1.com', 'http://user:pass@proxy-2.com'],\n     * });\n     *\n     * const crawler = new CheerioCrawler({\n     *   // ...\n     *   proxyConfiguration,\n     *   requestHandler({ proxyInfo }) {\n     *       const usedProxyUrl = proxyInfo.url; // Getting the proxy URL\n     *   }\n     * })\n     *\n     * ```\n     */\n    constructor(options: ProxyConfigurationOptions = {}) {\n        const { validateRequired, ...rest } = options as Dictionary;\n\n        if ('tieredProxyUrls' in rest) {\n            throw new Error(\n                'The `tieredProxyUrls` option has been removed in Crawlee v4. ' +\n                    'See the v4 upgrading guide for the recommended migration to named sessions.',\n            );\n        }\n\n        const { proxyUrls, newUrlFunction } = parseArgument(\n            rest as ProxyConfigurationOptions,\n            proxyConfigurationOptionsSchema,\n        );\n\n        if (proxyUrls && newUrlFunction) this.throwCannotCombineCustomMethods();\n        if (!proxyUrls && !newUrlFunction && validateRequired) this.throwNoOptionsProvided();\n\n        this.#proxyUrls = proxyUrls;\n        this.#newUrlFunction = newUrlFunction;\n    }\n\n    /**","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/core/src/proxy_configuration.ts#L100-L136","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading a project from Crawlee v3 to v4 without following the migration guide; copying old ProxyConfiguration snippets; shared config files that predate v4.","solutions":["Remove the tieredProxyUrls option from the ProxyConfigurationOptions object.","Migrate to the named-sessions approach per the Crawlee v4 upgrading guide.","Use proxyUrls (static list) or newUrlFunction (dynamic generation) instead.","Pin Crawlee to v3 temporarily if you cannot migrate yet (not recommended long-term)."],"exampleFix":"// before\nconst proxy = new ProxyConfiguration({ tieredProxyUrls: [['http://a', 'http://b']] });\n// after\nconst proxy = new ProxyConfiguration({ proxyUrls: ['http://a', 'http://b'] });","handlingStrategy":"validation","validationCode":"if ('tieredProxyUrls' in proxyOptions) {\n  throw new Error('tieredProxyUrls was removed in Crawlee v4; migrate to named sessions');\n}","typeGuard":null,"tryCatchPattern":"let proxy;\ntry {\n  proxy = new ProxyConfiguration(opts);\n} catch (err) {\n  if ((err as Error).message.includes('tieredProxyUrls')) {\n    const { tieredProxyUrls, ...rest } = opts;\n    proxy = new ProxyConfiguration(rest);\n  } else throw err;\n}","preventionTips":["Audit proxy configuration code when upgrading to Crawlee v4.","Read the v4 upgrading guide before migrating proxy settings.","Type options with ProxyConfigurationOptions so unknown keys fail type-check.","Add a startup assertion that legacy keys are absent."],"tags":["proxy","breaking-change","migration","configuration"],"backgroundTag":"option-removed-in-major-upgrade","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}