cube-js/cube · error

Unknown IANA timezone '${iana}'. Cannot convert to a Windows

Error message

Unknown IANA timezone '${iana}'. Cannot convert to a Windows timezone name for MSSQL AT TIME ZONE.

What it means

MSSQL AT TIME ZONE requires Windows timezone names, so Cube maps IANA tz names to Windows ones via a static lookup table. resolveWindowsTimezone throws when the given IANA identifier is absent from ianaToWindows (no equivalent mapping exists in the table).

Source

Thrown at packages/cubejs-schema-compiler/src/adapter/windows-iana.ts:460

  'Pacific/Palau': 'Tokyo Standard Time',
  'Pacific/Pitcairn': 'UTC-08',
  'Pacific/Ponape': 'Central Pacific Standard Time',
  'Pacific/Port_Moresby': 'West Pacific Standard Time',
  'Pacific/Rarotonga': 'Hawaiian Standard Time',
  'Pacific/Saipan': 'West Pacific Standard Time',
  'Pacific/Tahiti': 'Hawaiian Standard Time',
  'Pacific/Tarawa': 'UTC+12',
  'Pacific/Tongatapu': 'Tonga Standard Time',
  'Pacific/Truk': 'West Pacific Standard Time',
  'Pacific/Wake': 'UTC+12',
  'Pacific/Wallis': 'UTC+12',
  'UTC': 'UTC',
};

export function resolveWindowsTimezone(iana: string): string {
  const windowsTz = ianaToWindows[iana];
  if (!windowsTz) {
    throw new Error(
      `Unknown IANA timezone '${iana}'. Cannot convert to a Windows timezone name for MSSQL AT TIME ZONE.`
    );
  }

  return windowsTz;
}

View on GitHub (pinned to 7d981676b3)

Solutions

1. Use a widely supported IANA name that has a Windows equivalent (e.g. 'Europe/Kiev', 'America/New_York')
2. Normalize aliases first (e.g. via Intl API or moment-timezone) before calling
3. Update the ianaToWindows table (or file an issue/PR) if a legitimate zone is missing
4. Validate tz strings at config load time rather than at query time

Example fix

// before
resolveWindowsTimezone('Europe/Kyiv');
// after
resolveWindowsTimezone('Europe/Kiev'); // mapped entry in ianaToWindows

// optional pre-check against the mapping table
const known = require('./windows-iana');
const ianaToWindows = known.ianaToWindows || {};
const ok = iana in ianaToWindows || iana === 'UTC';

try { tz = resolveWindowsTimezone(iana); } catch (e) { if (e.message.startsWith('Unknown IANA timezone')) { tz = resolveWindowsTimezone(normalizeAlias(iana) || 'UTC'); } else throw e; }

When it happens

Trigger: Calling resolveWindowsTimezone(iana) (or windowsTz) with an IANA id not in the table — obscure zones, aliases, or invalid strings — typically while compiling an MSSQL query with a non-UTC timezone parameter.

Common situations: Setting timestamp precision/timezone in Cube config to a niche IANA zone (e.g. 'America/Argentina/ComodRivadavia' or a misspelled 'Europe/Kyiv' on an older table) with a MSSQL/ JDBC driver; using timezone strings from user input.

Related errors

• Unknown timezone: ${timezone}
• Value "${raw}" is not valid for CUBEJS_SCHEDULED_REFRESH_TIM
• Value "${value}" is not valid for CUBEJS_DEFAULT_TIMEZONE. M
• Timezone must be a string, got ${typeof value}
• Timezone must not be empty

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