proxyPolicy exception when calling new EmailClient(..) on Cloudflare Workers via Wrangler with nodejs_compat set

[kvanbere]

• Package Name: @azure/communication-email
• Package Version: npm:1.1.0
• Operating system: macOS Tahoe 26.3 (N/A)
• nodejs
  • version: N/A
• browser
  • name/version: N/A
• typescript
  • version: npm:5.9.3
• Is the bug related to documentation in
  • README.md
  • source code documentation
  • SDK API docs on https://learn.microsoft.com

Describe the bug
When running on Cloudflare Workers with nodejs_compat set per these instructions and like this:

const emailClient = new EmailClient(AZURE_ECS_CONNECTION_STRING);

an unexpected error is thrown:

| Failed to run background task: Error: proxyPolicy is not supported in browser environment
<stack trace>

To Reproduce
Steps to reproduce the behavior:

1. Set nodejs_compat in Cloudflare Wrangler:

    "compatibility_flags": [
        "nodejs_compat"
    ],
	"compatibility_date": "2026-02-21",

2. Call new EmailClient(...) from Cloudflare Workers

Expected behavior
The Azure SDK should not attempt to add the proxyPolicy to the fetch, and not throw an exception.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
Use this temporary workaround:

1. Create this file workaround-azure-proxy.ts:

// workaround-azure-proxy.ts

/**
 * The Azure SDK detects where it is running at the time of import.
 * If the node_compat flag is set in wrangler, it will detect Cloudflare Workers as a Node.js runtime.
 * This means that it will add a 'proxyPolicy' to the fetch pipeline, which isn't supported and throws an error.
 *
 * To avoid the error, this workaround needs to be imported right before @azure/communication-email.
 * It works by masking `process.versions` from the platform detection logic.
 */
if (typeof process !== 'undefined' && process.versions) {
  // Hide the Node version so Azure SDK thinks it is in a standard browser/worker env
  Object.defineProperty(process.versions, 'node', {
    value: undefined,
    writable: true,
  });
}

2. If your import looks like this:

import { EmailClient } from "@azure/communication-email";

then replace it with (order is important):

import './workaround-azure-proxy';
import { EmailClient } from "@azure/communication-email";

3. In your wrangler.jsonc, if it looks like this:

    "compatibility_flags": [
        "nodejs_compat"
    ],
    "compatibility_date": "2026-02-21",

then replace it like so (add disable_nodejs_process_v2 and no_nodejs_compat_v2):

    "compatibility_flags": [
        "nodejs_compat",
        "disable_nodejs_process_v2",
        "no_nodejs_compat_v2"
    ],
    "compatibility_date": "2026-02-21",

Not sure why the last step (3) is necessary to be honest, but it seems to be necessary.

[kvanbere]

It's not viable to remove nodejs_compat because so few libraries work, for example many libraries depend on Node crypto from there.

[jeremymeng]

I've been think of switching from throw to log a warning instead. Probably wouldn't harm too much if proxy setting is a no-op in browser environment?

[xirzec]

I like the idea of a no-op. We could also explicitly add workerd support like Identity has done

[kvanbere]

Workerd support would be great. Caution with a console warning: we’d probably end up paying to collect it in production through Cloudflare Observability, because console log is remapped to telemetry collection on workers.