motdotla/dotenv · error · Error

OBJECT_REQUIRED

OBJECT_REQUIRED

Error message

OBJECT_REQUIRED: Please check the processEnv argument being passed to populate

What it means

This error is thrown by dotenv's populate() helper when the processEnv argument is not a valid plain object. populate() copies parsed key/value pairs into a target object (usually process.env), and it explicitly validates that the target is assignable via Object.defineProperty / assignment. If you pass undefined, null, a primitive, or a non-object, dotenv aborts with code OBJECT_REQUIRED instead of silently failing.

Source

Thrown at lib/main.d.ts:121

  /**
   * Default: `process.env`
   *
   * Specify an object to write your secrets to. Defaults to process.env environment variables.
   *
   * example: `const processEnv = {}; require('dotenv').config({ processEnv: processEnv })`
   */
  processEnv?: DotenvPopulateInput;

}

export interface DotenvConfigOutput {
  error?: DotenvError;
  parsed?: DotenvParseOutput;
}

type DotenvError = Error & {
  code: 'OBJECT_REQUIRED' | 'SECURE_REQUIRES_DOTENVX';
}

export interface DotenvPopulateOptions {
  /**
   * Default: `false`
   *
   * Turn on logging to help debug why certain keys or values are not being set as you expect.
   *
   * example: `require('dotenv').populate(processEnv, parsed, { debug: true })`
   */
  debug?: boolean;

  /**
   * Default: `false`
   *
   * Override any environment variables that have already been set on your machine with values from your .env file.
   *
   * example: `require('dotenv').populate(processEnv, parsed, { override: true })`

View on GitHub (pinned to 2fc7eac8ad)

Solutions

Pass a real object as the processEnv argument — typically process.env itself: dotenv.populate(parsed, process.env).
If you use a custom target, initialize it first: const env = {}; dotenv.populate(parsed, env).
Check argument order: the signature is populate(processEnv, parsed) — make sure the target object is first, not the parsed result.
Log/inspect the value right before the call (console.log(typeof processEnv)) to confirm it is 'object' and not null/undefined.
If running in an environment where process is not defined (edge/serverless), create a shim object instead of relying on a missing global.

Example fix

// before
const parsed = dotenv.config().parsed
dotenv.populate(parsed, myEnv) // myEnv is undefined -> OBJECT_REQUIRED

// after
const parsed = dotenv.config().parsed
const myEnv = myEnv || {}
dotenv.populate(myEnv, parsed) // correct order, valid object target

Defensive patterns

Strategy: validation

Validate before calling

function canPopulate(target) {
  return typeof target === 'object' && target !== null
}
// before calling:
if (!canPopulate(myEnv)) throw new TypeError('populate requires an object as processEnv')

Type guard

function isPopulateTarget(v: unknown): v is Record<string, string> {
  return typeof v === 'object' && v !== null
}

Try / catch

try {
  dotenv.populate(processEnv, parsed)
} catch (err: any) {
  if (err && err.code === 'OBJECT_REQUIRED') {
    console.error('populate() target must be an object; got', typeof processEnv)
    processEnv = processEnv && typeof processEnv === 'object' ? processEnv : {}
    dotenv.populate(processEnv, parsed)
  } else {
    throw err
  }
}

Prevention

Always pass process.env (or a freshly created {}) as the populate target — never a variable that may be undefined.
Enable TypeScript strict mode so the lib/main.d.ts typing (DotenvPopulateOptions / processEnv: object) catches bad arguments at compile time.
Keep argument order straight: target object first, parsed result second.
In serverless/edge runtimes, verify the process global exists before calling any dotenv API.
Wrap populate() calls in a small utility that validates inputs once instead of calling it ad hoc.

When it happens

Trigger: Calling dotenv.populate(parsed, processEnv) where processEnv is undefined/null (e.g. a variable that was never assigned), or passing a primitive such as a string, number, or boolean, or passing an object created with Object.create(null) in older versions lacking a prototype, or calling the typed overload from lib/main.d.ts:121 with mismatched arguments so the target argument is missing at runtime.

Common situations: Refactoring code so the second argument to populate() was accidentally dropped or renamed; importing populate() and swapping the argument order (passing the parsed object where the env target belongs); storing process.env in a variable that ends up undefined in a bundled/SSR environment (e.g. serverless or edge runtimes where process is polyfilled oddly); calling populate() before any target object exists in custom env-loading utilities.

AI-assisted analysis of motdotla/dotenv@2fc7eac8ad (2026-09-02). Data as JSON: /api/errors/7eb3cf36487607f1. Report an issue: GitHub.