dotenv

Postconditions — what we check

• config · missing-env-file

  info
  When.env file does not exist or cannot be read
  ReturnsObject with 'error' property containing the Error instance
  Required handlingCaller MAY check result.error after calling config(). config() does NOT throw on missing .env files — it returns { error }. Most callers intentionally ignore the return value because missing .env is expected in production (env vars set via platform). Only check in development/local.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1][2]
• config · parse-error

  info
  When.env file exists but contains a syntax error
  ReturnsObject with 'error' property containing the parse Error instance
  Required handlingCaller MAY check result.error. config() does NOT throw on parse errors — it returns { error }. Unhandled parse errors silently leave process.env in a partially-populated state.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1][2]
• config · vault-invalid-dotenv-key

  error
  WhenDOTENV_KEY is set but is malformed (wrong URI format, missing key part, missing environment part, or key is shorter than 64 hex characters)
  ThrowsError with code 'INVALID_DOTENV_KEY'. Messages include: "Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/...", "Missing key part", "Missing environment part", "It must be 64 characters long (or more)".
  Required handlingWhen using .env.vault with DOTENV_KEY, callers MUST wrap config() in a try-catch block. In vault mode config() throws (does not return {error}). A malformed key causes an immediate exception that will crash the process if uncaught.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• config · vault-environment-not-found

  error
  WhenDOTENV_KEY references an environment (e.g. 'production') but the corresponding DOTENV_VAULT_PRODUCTION key is not found in the .env.vault file
  ThrowsError with code 'NOT_FOUND_DOTENV_ENVIRONMENT'. Message: "Cannot locate environment DOTENV_VAULT_<ENVIRONMENT> in your .env.vault file."
  Required handlingWrap config() in try-catch when using vault mode. This error occurs when the vault was built for a different environment than the key references. Common during deployments when DOTENV_KEY from staging is accidentally used in production.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• config · vault-decryption-failed

  error
  WhenDOTENV_KEY is syntactically valid but does not decrypt the vault ciphertext (wrong key for the environment, rotated key no longer matches)
  ThrowsError with code 'DECRYPTION_FAILED'. Message: "Please check your DOTENV_KEY".
  Required handlingWrap config() in try-catch when using vault mode. This is the most common vault error in production — it occurs when the DOTENV_KEY env var is stale or belongs to a different environment's vault. Application starts with no secrets loaded.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• config · vault-missing-data

  error
  WhenThe .env.vault file exists (detected because DOTENV_KEY is set) but its contents cannot be parsed (empty file, corrupted, wrong format)
  ThrowsError with code 'MISSING_DATA'. Message: "Cannot parse <vaultPath> for an unknown reason".
  Required handlingWrap config() in try-catch when using vault mode. A corrupted or empty vault file causes an immediate throw. Secrets are not loaded.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• config · success

  info
  When.env file is found and parsed successfully
  ReturnsObject with 'parsed' key containing the parsed key-value pairs
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• configDotenv · configdotenv-file-not-found

  error
  WhenOne or more paths in options.path do not exist or cannot be read
  ReturnsObject with 'error' property set to the last filesystem error encountered. The 'parsed' key is still present with whatever keys were successfully loaded from other files.
  Required handlingCaller MUST check result.error. When path is an array, configDotenv() continues loading remaining files on error (lastError tracking) but the final result includes the error from the last failed file. Silently missing .env files are a common misconfiguration in containerized deployments.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[3]
• configDotenv · configdotenv-partial-load-on-multi-path

  warning
  Whenoptions.path is an array of multiple file paths and some exist while others do not
  ReturnsObject with 'parsed' containing keys from successfully loaded files only. 'error' is set to the last error from any failed file even if other files loaded successfully.
  Required handlingWhen using multiple paths, callers relying on all files being present MUST validate result.error AND verify all expected keys exist in result.parsed. The presence of result.error does not mean zero keys were loaded.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[3]
• parse · parse-silent-skip-on-malformed-lines

  warning
  WhenInput string contains lines that do not match the KEY=VALUE pattern
  ReturnsPlain object containing only the lines that did match. Malformed lines are silently dropped. Return value may be an empty object if no lines match.
  Required handlingCallers MUST NOT rely on parse() throwing to detect malformed input. Silent partial parsing means the returned object may be missing expected keys without any error signal. Callers that need strict validation must implement their own key-presence checks after calling parse().
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[3]
• parse · success

  info
  Wheninput is a valid .env-format string or Buffer
  ReturnsPlain object with string keys and string values
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• populate · no-override-by-default

  warning
  Whena key already exists on the target object and override is not set to true
  ReturnsExisting value is preserved; parsed value is ignored
  Required handlingCallers that intend to force-update existing values MUST pass { override: true }. Omitting this option causes pre-existing environment variables (e.g., set by the OS or CI) to silently take precedence.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• populate · populate-object-required

  error
  WhenThe parsed argument passed to populate() is not an object (e.g. null, string, number)
  ThrowsError with code 'OBJECT_REQUIRED'. Message: "Please check the processEnv argument being passed to populate".
  Required handlingCallers that build the parsed input dynamically (e.g. from JSON.parse of untrusted input) MUST validate the input is an object before calling populate(). Passing null or a primitive throws synchronously and bypasses any surrounding error handling that only catches async errors.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• decrypt · decrypt-invalid-key-length

  error
  WhenkeyStr is shorter than 64 hex characters (the last 64 chars are sliced for the AES key; a shorter string produces an invalid 32-byte key)
  ThrowsError with code 'INVALID_DOTENV_KEY'. Message: "It must be 64 characters long (or more)".
  Required handlingCallers MUST wrap decrypt() in try-catch. This error indicates the DOTENV_KEY was truncated or corrupted. Attempting decryption with a short key will crash the process.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• decrypt · decrypt-wrong-key

  error
  WhenkeyStr is the correct length but does not decrypt the ciphertext (wrong environment key, key rotation mismatch, or ciphertext tampered with)
  ThrowsError with code 'DECRYPTION_FAILED'. Message: "Please check your DOTENV_KEY". Internally triggered by AES-GCM authentication tag verification failure ("Unsupported state or unable to authenticate data").
  Required handlingWrap decrypt() in try-catch. This is the most actionable error — it means the key and ciphertext do not correspond. Common during key rotation when old ciphertext is paired with a new key. Silent swallowing of this error leaves secrets unloaded.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/motdotla/dotenvhttps://github.com/motdotla/dotenv#config
2. [2]npmjs.com/package/dotenvhttps://www.npmjs.com/package/dotenv
3. [3]github.com/motdotla/dotenvhttps://github.com/motdotla/dotenv/blob/master/lib/main.js
4. [4]github.com/motdotla/dotenvhttps://github.com/motdotla/dotenv#parse
5. [5]github.com/motdotla/dotenvhttps://github.com/motdotla/dotenv#populate