toeverything/AFFiNE · critical · Error

Invalid value " " for environment variable , expected one of

Error message

Invalid value "${value}" for environment variable ${env}, expected one of ${JSON.stringify(availableValues)}

What it means

Thrown by the global readEnv(env, defaultValue, availableValues) helper during Env construction when an environment variable restricted to an enum is set to a value outside the allowed list. Validated variables include AFFINE_ENV (dev|beta|production), DEPLOYMENT_TYPE (affine|selfhosted), and SERVER_FLAVOR (allinone|graphql|sync|renderer|front|doc|script).

Solutions

1. Set the variable to one of the values printed in the error's 'expected one of' list, e.g. AFFINE_ENV=beta (not staging).
2. Unset the variable if you want the default instead of guessing a value.
3. Check src/env.ts enums (Namespace, DeploymentType, Flavor) for your server version to see the accepted values.

Example fix

# before
AFFINE_ENV=staging
# after
AFFINE_ENV=beta

// Fail fast with a friendly message before booting the app
const ALLOWED = {
  AFFINE_ENV: ['dev', 'beta', 'production'],
  DEPLOYMENT_TYPE: ['affine', 'selfhosted'],
  SERVER_FLAVOR: ['allinone', 'graphql', 'sync', 'renderer', 'front', 'doc', 'script'],
};
for (const [key, values] of Object.entries(ALLOWED)) {
  const v = process.env[key];
  if (v && !values.includes(v)) {
    console.error(`${key}=${v} invalid; expected one of ${values.join('|')}`);
    process.exit(1);
  }
}

const isValidAffineEnv = (value: string): boolean =>
  ['dev', 'beta', 'production'].includes(value);

When it happens

Trigger: Starting the server with e.g. AFFINE_ENV=staging, DEPLOYMENT_TYPE=cloud, or SERVER_FLAVOR=api — any value not in that variable's enum.

Common situations: Copying docker-compose/.env from other projects that use different conventions (staging instead of beta); typos; using a value valid in an older/newer AFFiNE version after upgrading.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Invalid NODE_ENV environment.
• unknown_oauth_provider
• action_forbidden
• blob_invalid
• caldav_insecure_url

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

Appendix: source

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

  NAMESPACE: Namespace;
  DEPLOYMENT_TYPE: DeploymentType;
  version: string;
};

globalThis.CLS_REQUEST_HOST = 'CLS_REQUEST_HOST';
globalThis.CUSTOM_CONFIG_PATH = join(homedir(), '.affine/config');
globalThis.readEnv = function readEnv<T>(
  env: string,
  defaultValue: T,
  availableValues?: T[]
) {
  const value = process.env[env];
  if (value === undefined) {
    return defaultValue;
  }

  if (availableValues && !availableValues.includes(value as any)) {
    throw new Error(
      `Invalid value "${value}" for environment variable ${env}, expected one of ${JSON.stringify(
        availableValues
      )}`
    );
  }

  return value as T;
};

export class Env implements AppEnv {
  NODE_ENV = (process.env.NODE_ENV ?? NodeEnv.Production) as NodeEnv;
  NAMESPACE = readEnv(
    'AFFINE_ENV',
    Namespace.Production,
    Object.values(Namespace)
  );
  DEPLOYMENT_TYPE = readEnv(
    'DEPLOYMENT_TYPE',

View on GitHub (pinned to 591f874dad)