cube-js/cube · error · InvalidConfiguration

Value "${value}" is not valid for CUBEJS_DEFAULT_TIMEZONE. M

Error message

Value "${value}" is not valid for CUBEJS_DEFAULT_TIMEZONE. Must be a valid IANA time zone name, e.g. UTC or America/Los_Angeles.

What it means

Environment validation in env.ts defaultTimezone accessor: the CUBEJS_DEFAULT_TIMEZONE environment variable is set but is not a valid IANA time zone name (validated via Intl/DateTimeFormat), so the default timezone cannot be resolved. Fires at first getEnv('defaultTimezone') call during startup.

Source

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

  allowNonStrictDateRangeMatching: () => get('CUBEJS_PRE_AGGREGATIONS_ALLOW_NON_STRICT_DATE_RANGE_MATCH')
    .default('true')
    .asBoolStrict(),
  transpilationWorkerThreadsCount: () => get('CUBEJS_TRANSPILATION_WORKER_THREADS_COUNT')
    .default('0')
    .asInt(),
  // This one takes precedence over CUBEJS_TRANSPILATION_WORKER_THREADS
  transpilationNative: () => get('CUBEJS_TRANSPILATION_NATIVE')
    .default('false')
    .asBoolStrict(),
  nestedFoldersDelimiter: () => get('CUBEJS_NESTED_FOLDERS_DELIMITER')
    .default('')
    .asString(),
  defaultTimezone: () => {
    const value = (get('CUBEJS_DEFAULT_TIMEZONE').asString() || '').trim() || 'UTC';

    const timezone = canonicalTimezone(value);
    if (!timezone) {
      throw new InvalidConfiguration(
        'CUBEJS_DEFAULT_TIMEZONE',
        value,
        'Must be a valid IANA time zone name, e.g. UTC or America/Los_Angeles.'
      );
    }

    return timezone;
  },
  preciseDecimalInCubestore: () => get('CUBEJS_DB_PRECISE_DECIMAL_IN_CUBESTORE')
    .default('false')
    .asBoolStrict(),
  refreshKeyLocalTime: () => get('CUBEJS_REFRESH_KEY_LOCAL_TIME')
    .default('false')
    .asBoolStrict(),

  /** ****************************************************************
   * Common db options                                               *
   ***************************************************************** */

View on GitHub (pinned to 7d981676b3)

Solutions

Set CUBEJS_DEFAULT_TIMEZONE to a valid IANA name such as UTC or America/Los_Angeles.
Remove the variable entirely to fall back to UTC as the default timezone.
Check for abbreviations like PST or EST, which are not IANA names and will be rejected.

Example fix

// before
CUBEJS_DEFAULT_TIMEZONE=EST
// after
CUBEJS_DEFAULT_TIMEZONE=America/New_York

Defensive patterns

Strategy: validation

Validate before calling

const tz = process.env.CUBEJS_DEFAULT_TIMEZONE;
if (tz) {
  try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); }
  catch { throw new Error(`CUBEJS_DEFAULT_TIMEZONE '${tz}' is not a valid IANA time zone`); }
}

Try / catch

try {
  configureTimezones();
} catch (e) {
  if (String(e.message).includes('CUBEJS_DEFAULT_TIMEZONE')) {
    console.error('Set CUBEJS_DEFAULT_TIMEZONE to an IANA name like UTC or America/New_York');
    process.exit(1);
  }
  throw e;
}

Prevention

Prefer UTC unless a specific zone is required.
Test the value with new Intl.DateTimeFormat(..., { timeZone: value }) before deploy.
Never use fixed offsets like GMT+2; use Etc/GMT±h names if needed.

When it happens

Trigger: Setting CUBEJS_DEFAULT_TIMEZONE to something like 'PST', 'GMT+2', 'US Eastern', or a misspelled zone so canonicalTimezone returns falsy.

Common situations: Copy-pasting offsets instead of zone names; typo in a zone like 'America/LosAngeles' (missing underscore); locale-specific zone names from Windows registries.

Related errors

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