cube-js/cube · error · InvalidConfiguration

Value "${raw}" is not valid for CUBEJS_SCHEDULED_REFRESH_TIM

Error message

Value "${raw}" is not valid for CUBEJS_SCHEDULED_REFRESH_TIMEZONES. Must be a comma-separated list of valid IANA time zone names, e.g. UTC,America/Los_Angeles.

What it means

CUBEJS_SCHEDULED_REFRESH_TIMEZONES must be a comma-separated list of IANA time zone names; each entry is passed through canonicalTimezone and entries that cannot be canonicalized make Cube throw InvalidConfiguration. This ensures pre-aggregation refresh scheduling uses recognizable zones.

Source

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

    }

    // It's true by default for development
    return process.env.NODE_ENV !== 'production';
  },
  scheduledRefreshQueriesPerAppId: () => get('CUBEJS_SCHEDULED_REFRESH_QUERIES_PER_APP_ID').asIntPositive(),
  refreshWorkerConcurrency: () => get('CUBEJS_REFRESH_WORKER_CONCURRENCY')
    .asIntPositive(),
  scheduledRefreshTimezones: () => {
    const timezones = get('CUBEJS_SCHEDULED_REFRESH_TIMEZONES')
      .default('')
      .asArray()
      .map(timezone => timezone.trim())
      .filter(Boolean);

    return timezones.map(raw => {
      const timezone = canonicalTimezone(raw);
      if (!timezone) {
        throw new InvalidConfiguration(
          'CUBEJS_SCHEDULED_REFRESH_TIMEZONES',
          raw,
          'Must be a comma-separated list of valid IANA time zone names, e.g. UTC,America/Los_Angeles.'
        );
      }

      return timezone;
    });
  },
  preAggregationsBuilder: () => get('CUBEJS_PRE_AGGREGATIONS_BUILDER').asBool(),
  gracefulShutdown: () => get('CUBEJS_GRACEFUL_SHUTDOWN')
    .asIntPositive(),
  dockerImageVersion: () => get('CUBEJS_DOCKER_IMAGE_VERSION')
    .asString(),
  concurrency: ({
    dataSource,
  }: {
    dataSource: string,

View on GitHub (pinned to 7d981676b3)

Solutions

Replace abbreviations with IANA names, e.g. America/Los_Angeles instead of PST.
Validate each entry against the IANA database (Intl.supportedValuesOf('timeZone') in Node 18+).
Remove empty/extra commas and ensure entries are separated by single commas.
Test with Node: new Intl.DateTimeFormat('en-US',{timeZone:'Your/Zone'}) — if it throws, fix the name.

Example fix

// before
CUBEJS_SCHEDULED_REFRESH_TIMEZONES=UTC,PST,America/New_York
// after
CUBEJS_SCHEDULED_REFRESH_TIMEZONES=UTC,America/Los_Angeles,America/New_York

Defensive patterns

Strategy: validation

Validate before calling

const zones = (process.env.CUBEJS_SCHEDULED_REFRESH_TIMEZONES || '').split(',').map(s => s.trim()).filter(Boolean);
const valid = new Set(Intl.supportedValuesOf ? Intl.supportedValuesOf('timeZone') : ['UTC']);
const bad = zones.filter(z => !valid.has(z));
if (bad.length) throw new Error(`Invalid IANA time zones: ${bad.join(', ')}`);

Try / catch

try {
  configureScheduledRefresh();
} catch (e) {
  if (String(e.message).includes('CUBEJS_SCHEDULED_REFRESH_TIMEZONES')) {
    console.error('Use comma-separated IANA names, e.g. UTC,America/Los_Angeles');
    process.exit(1);
  }
  throw e;
}

Prevention

Use full IANA names (America/Los_Angeles), never abbreviations (PST).
Validate zone lists with Intl.supportedValuesOf('timeZone') in CI.
Avoid double commas and trailing commas.

When it happens

Trigger: Setting CUBEJS_SCHEDULED_REFRESH_TIMEZONES with an entry that is not a valid IANA name, e.g. 'UTC,PST' or 'America/New York' (space, unquoted) or 'america/los_angeles' if canonicalization is case-sensitive, or an empty entry like 'UTC,,Europe/Berlin' (empties are filtered, but misspelled names throw).

Common situations: Using abbreviations (PST, EST, CET) instead of IANA names; typos like 'Amercia/New_York'; copy-pasting a list with stray whitespace or trailing commas; Windows-style zone names.

Related errors

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