denoland/deno · error · ERR_INVALID_ARG_TYPE

ERR_INVALID_ARG_TYPE

ERR_INVALID_ARG_TYPE

Error message

The "options.env" property must be of type object or one of undefined, null, or worker_threads.SHARE_ENV. Received ${envOpt}

What it means

Worker's env option follows Node semantics: undefined/null snapshots the parent env, worker_threads.SHARE_ENV shares the live OS environment, and an object is copied with String()-coerced values into a structured-clone-safe snapshot. Any other type — string, number, boolean — fails the typeof check and throws ERR_INVALID_ARG_TYPE('options.env', ...) with the accepted-type list embedded in the message.

Source

Thrown at ext/node/polyfills/worker_threads.ts:421

        }
      }
    }

    // Serialize workerData before resolving the filename so that
    // DataCloneError is thrown before file-not-found errors,
    // matching Node.js behavior.

    // Handle the `env` option following Node.js semantics:
    // - undefined/null: snapshot current lazyProcess().default.env (isolated copy)
    // - SHARE_ENV: worker shares the parent's OS environment
    // - object: use that object, coercing values to strings
    // - anything else: throw ERR_INVALID_ARG_TYPE
    // See https://github.com/denoland/deno/issues/23522.
    let env_ = undefined;
    const envOpt = options?.env;
    if (envOpt != null && envOpt !== SHARE_ENV) {
      if (typeof envOpt !== "object") {
        throw new ERR_INVALID_ARG_TYPE(
          "options.env",
          ["object", "undefined", "null", "worker_threads.SHARE_ENV"],
          envOpt,
        );
      }
      // Snapshot the provided env, coercing values to strings like Node.js.
      // This also handles passing `lazyProcess().default.env` (a Proxy in Deno) by
      // producing a plain object that can be structured-cloned.
      const envObj = {};
      const keys = ObjectKeys(envOpt);
      for (let i = 0; i < keys.length; i++) {
        envObj[keys[i]] = String(envOpt[keys[i]]);
      }
      env_ = envObj;
    } else if (envOpt !== SHARE_ENV) {
      // Default: snapshot current lazyProcess().default.env so the worker gets an
      // isolated copy, not a live reference to the OS environment.
      // Wrap in try/catch because accessing lazyProcess().default.env requires

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. Pass a plain object: { env: { NODE_ENV: 'production', DEBUG: 'app:*' } }.
2. To share the parent's live environment, pass worker_threads.SHARE_ENV.
3. To inherit a snapshot, simply omit env (or pass null).
4. If env arrives serialized, parse it first: { env: JSON.parse(envJson) }.

Example fix

// before
const w = new Worker(f, { env: 'production' });

// after
import { SHARE_ENV, Worker } from 'node:worker_threads';
const w = new Worker(f, { env: { NODE_ENV: 'production' } });
// or share the parent's live env:
const w2 = new Worker(f, { env: SHARE_ENV });

import { SHARE_ENV } from 'node:worker_threads';

if (env !== undefined && env !== null && env !== SHARE_ENV && typeof env !== 'object') {
  throw new TypeError('options.env must be an object, undefined, null, or SHARE_ENV');
}
const w = new Worker(f, { env });

function isValidWorkerEnv(v: unknown): v is Record<string, string> | undefined | null {
  return v == null || v === SHARE_ENV || typeof v === 'object';
}

When it happens

Trigger: new Worker(f, { env: 'production' }), { env: 123 }, or { env: true } — a non-object, non-nullish value that is not SHARE_ENV.

Common situations: Confusing env (a key-to-value map) with a NODE_ENV-style name; passing a JSON.stringify()'d env received from CI variables or message queues; copy-paste from CLI docs where env values are strings.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Cannot convert a Symbol value to a string
• ERR_INVALID_OBJECT_DEFINE_PROPERTY
• ERR_INSPECTOR_NOT_WORKER
• ERR_WORKER_UNSUPPORTED_OPERATION
• ERR_WORKER_INVALID_EXEC_ARGV

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/602b0324bad5dabf. Report an issue: GitHub.