cube-js/cube · error · Error

Unsupported env variable: "${key}"

Error message

Unsupported env variable: "${key}"

What it means

Unknown-key guard in getEnv (cubejs-backend-shared/env.ts): the requested env accessor key is not present in the `variables` registry. This fires when code (often a driver or package) calls getEnv with a key the installed env.ts does not define — usually a version mismatch between packages, not a user environment problem.

Source

Thrown at packages/cubejs-backend-shared/src/env.ts:2102

    .asBoolStrict(),
  accessPolicyMaskString: () => get('CUBEJS_ACCESS_POLICY_MASK_STRING')
    .asString(),
  accessPolicyMaskTime: () => get('CUBEJS_ACCESS_POLICY_MASK_TIME')
    .asString(),
  accessPolicyMaskBoolean: () => get('CUBEJS_ACCESS_POLICY_MASK_BOOLEAN')
    .asString(),
  accessPolicyMaskNumber: () => get('CUBEJS_ACCESS_POLICY_MASK_NUMBER')
    .asString(),
};

type Vars = typeof variables;

export function getEnv<T extends keyof Vars>(key: T, opts?: Parameters<Vars[T]>): ReturnType<Vars[T]> {
  if (key in variables) {
    return variables[key](opts);
  }

  throw new Error(
    `Unsupported env variable: "${key}"`,
  );
}

// trigger warning
getEnv('transpilationWorkerThreads');

export function isDockerImage(): boolean {
  return Boolean(process.env.CUBEJS_DOCKER_IMAGE_TAG);
}

View on GitHub (pinned to 7d981676b3)

Solutions

1. Check the exact getEnv key spelling against the CUBEJS_* names exported in env.ts.
2. Align package versions: a driver referencing a newer env variable than the installed cubejs-backend-shared defines will trigger this.
3. After upgrading packages, run yarn install and rebuild so the env registry matches all consumers.

When it happens

Trigger: Thrown at packages/cubejs-backend-shared/src/env.ts:2102 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/8eecf01e233fd39c. Report an issue: GitHub.