apify/crawlee · error · Error

One of "options.proxyUrls" or "options.newUrlFunction" needs

Error message

One of "options.proxyUrls" or "options.newUrlFunction" needs to be provided.

What it means

A ProxyConfiguration must be given at least one proxy source: a static proxyUrls array or a dynamic newUrlFunction. If neither is provided (and validateRequired isn't bypassing), the constructor throws this error because the configuration would have no proxies to hand out.

Source

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

            if (proxyUrl) {
                new URL(proxyUrl); // eslint-disable-line no-new
            }
            return proxyUrl;
        } catch (err) {
            throw new Error(
                `The provided newUrlFunction did not return a valid URL.\nCause: ${(err as Error).message}`,
            );
        }
    }

    private throwCannotCombineCustomMethods(): never {
        throw new Error(
            'Cannot combine custom proxies "options.proxyUrls" with custom generating function "options.newUrlFunction".',
        );
    }

    private throwNoOptionsProvided(): never {
        throw new Error('One of "options.proxyUrls" or "options.newUrlFunction" needs to be provided.');
    }
}

View on GitHub (pinned to dbe57fb09c)

Solutions

1. Provide proxyUrls: new ProxyConfiguration({ proxyUrls: ['http://proxy:8000'] }).
2. Or provide newUrlFunction returning a proxy URL dynamically.
3. Check that the env vars/config feeding the options are actually set before constructing.
4. If proxies are genuinely optional, conditionally construct ProxyConfiguration only when options exist.

Example fix

// before
const proxy = new ProxyConfiguration({}); // throws
// after
const opts = process.env.PROXY_URLS ? { proxyUrls: process.env.PROXY_URLS.split(',') } : undefined;
const proxy = opts ? new ProxyConfiguration(opts) : undefined;

const hasProxySource = Boolean(opts?.proxyUrls?.length || opts?.newUrlFunction);
if (!hasProxySource) {
  throw new Error('ProxyConfiguration requires proxyUrls or newUrlFunction');
}

function hasProxyOptions(o: unknown): o is { proxyUrls?: string[]; newUrlFunction?: () => string } {
  const v = o as any;
  return v && (Array.isArray(v.proxyUrls) && v.proxyUrls.length > 0 || typeof v.newUrlFunction === 'function');
}

try {
  proxy = new ProxyConfiguration(opts);
} catch (err) {
  if ((err as Error).message.includes('needs to be provided')) {
    console.warn('No proxy configured; running without proxy');
    proxy = undefined;
  } else throw err;
}

When it happens

Trigger: Calling new ProxyConfiguration() with an empty object, or with an options object from which both proxyUrls and newUrlFunction are absent/undefined (e.g. empty env-derived config).

Common situations: Environment variables for proxies unset so parsed options end up empty; spreading an empty/partial config; forgetting to pass options when switching from a constructor that required them.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}.
• The `tieredProxyUrls` option has been removed in Crawlee v4.
• The provided newUrlFunction did not return a valid URL. Caus
• Cannot combine custom proxies "options.proxyUrls" with custo
• PlaywrightCrawlerOptions.launchContext.proxyUrl is not allow

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