cube-js/cube · error · InvalidConfiguration

Value "${input}" is not valid for ${envName}. ${description}

Error message

Value "${input}" is not valid for ${envName}. ${description}

What it means

convertTimeStrToSeconds parses env values as plain seconds ("30") or duration strings ending in h/m/s ("1h", "15m"). If the value matches neither form (or the numeric part is not an integer), it throws InvalidConfiguration naming the env variable and the expected format. This protects Cube from silently misinterpreting durations.

Source

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

  description: string = 'Must be a number in seconds or duration string (1s, 1m, 1h).',
) {
  if (/^\d+$/.test(input)) {
    return parseInt(input, 10);
  }

  if (input.length > 1) {
    // eslint-disable-next-line default-case
    switch (input.slice(-1).toLowerCase()) {
      case 'h':
        return parseInt(input.slice(0, -1), 10) * 60 * 60;
      case 'm':
        return parseInt(input.slice(0, -1), 10) * 60;
      case 's':
        return parseInt(input.slice(0, -1), 10);
    }
  }

  throw new InvalidConfiguration(envName, input, description);
}

export function convertSizeToBytes(
  input: string,
  envName: string,
  description: string = 'Must be a number in bytes or size string (1kb, 1mb, 1gb).',
): number {
  if (/^\d+$/.test(input)) {
    return parseInt(input, 10);
  }

  if (input.length > 2) {
    switch (input.slice(-2).toLowerCase()) {
      case 'kb':
        return parseInt(input.slice(0, -2), 10) * 1024;
      case 'mb':
        return parseInt(input.slice(0, -2), 10) * 1024 * 1024;
      case 'gb':

View on GitHub (pinned to 7d981676b3)

Solutions

Set the env var to a plain integer of seconds (e.g. 3600) or a string ending in h, m, or s with an integer prefix (e.g. 1h, 15m, 30s).
Check for stray quotes, whitespace, or comments inside the .env value.
Convert decimals to whole units (0.5h -> 30m).

Example fix

// before (.env)
CUBEJS_SCHEDULED_REFRESH_TIMER=1hr

// after (.env)
CUBEJS_SCHEDULED_REFRESH_TIMER=1h

Defensive patterns

Strategy: validation

Validate before calling

const raw = process.env.CUBEJS_SCHEDULED_REFRESH_TIMER;
if (raw !== undefined && !/^\d+$/.test(raw) && !/^\d+[hms]$/i.test(raw)) {
  throw new Error(`CUBEJS_SCHEDULED_REFRESH_TIMER="${raw}" must be seconds (3600) or a duration like 1h, 15m, 30s.`);
}

Type guard

function isValidTimeStr(v: string): boolean {
  return /^\d+$/.test(v) || /^\d+[hms]$/i.test(v);
}

Try / catch

try {
  startCubeServer();
} catch (e) {
  if (e instanceof InvalidConfiguration && e.message.includes('Must be a number in seconds or duration string')) {
    console.error('Fix the duration env var: use 30, 30s, 15m, or 1h.');
    process.exit(1);
  }
  throw e;
}

Prevention

Use whole-unit suffixes only: h, m, s (1h, 15m, 30s) — not hr, sec, or min.
Prefer plain integer seconds in env files to avoid suffix mistakes.
Convert decimals to whole units (0.5h -> 30m).
Validate .env values in CI with a small pre-flight script before deploying.

When it happens

Trigger: Setting a duration-related env var (consumed via asBoolOrTime/variables, e.g. CUBEJS_SCHEDULED_REFRESH_TIMER or external timeout vars) to something like "1hr", "one hour", "1.5h", "h", or an empty string.

Common situations: Typos like "1hr" or "90sec" in .env files; copy-pasting human-readable durations into env config; forgetting a unit suffix entirely; using decimal values like "0.5h".

Related errors

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