toeverything/AFFiNE · critical · Error

Invalid NODE_ENV environment. `${this.NODE_ENV}` is not a va

Error message

Invalid NODE_ENV environment. `${this.NODE_ENV}` is not a valid NODE_ENV value.

What it means

Thrown by the Env class constructor when NODE_ENV is set to anything other than development, test, or production (the NodeEnv enum). The value defaults to production when unset, so this only fires when a bad value was explicitly provided; the process fails at env creation time.

Source

Thrown at packages/backend/server/src/env.ts:186

  get testing() {
    return this.NODE_ENV === NodeEnv.Test;
  }

  get dev() {
    return this.NODE_ENV === NodeEnv.Development;
  }

  get prod() {
    return this.NODE_ENV === NodeEnv.Production;
  }

  get gcp() {
    return this.platform === Platform.GCP;
  }

  constructor() {
    if (!Object.values(NodeEnv).includes(this.NODE_ENV)) {
      throw new Error(
        `Invalid NODE_ENV environment. \`${this.NODE_ENV}\` is not a valid NODE_ENV value.`
      );
    }
  }
}

export const createGlobalEnv = () => {
  if (!globalThis.env) {
    globalThis.env = new Env();
  }
};

View on GitHub (pinned to 591f874dad)

Solutions

1. Use one of the full words: NODE_ENV=development, NODE_ENV=test, or NODE_ENV=production.
2. Remove NODE_ENV entirely if production is intended (it is the default).
3. Audit docker-compose/CI matrix so no stage-specific custom values leak into NODE_ENV (use AFFINE_ENV=beta for stage separation instead).

Example fix

# before
NODE_ENV=dev
# after
NODE_ENV=development

// Preflight check in a bootstrap script
const NODE_ENVS = ['development', 'test', 'production'];
if (process.env.NODE_ENV && !NODE_ENVS.includes(process.env.NODE_ENV)) {
  throw new Error(`NODE_ENV must be one of ${NODE_ENVS.join('|')} (or unset)`);
}

const isValidNodeEnv = (value: string): boolean =>
  ['development', 'test', 'production'].includes(value);

When it happens

Trigger: Starting the server with NODE_ENV=staging, NODE_ENV=dev, NODE_ENV=prod, or any non-enum value — note that abbreviations like 'dev'/'prod' are NOT accepted.

Common situations: Porting NODE_ENV from another framework that permits arbitrary values; writing NODE_ENV=dev out of habit; CI pipelines injecting a custom stage name.

Related errors

• Invalid value "${value}" for environment variable ${env}, ex
• unknown_oauth_provider
• sign_up_forbidden
• invalid_email
• email_service_not_configured

AI-assisted analysis of toeverything/AFFiNE@591f874dad (2026-08-18). Data as JSON: /api/errors/b02958720aa65383. Report an issue: GitHub.