cube-js/cube · error · InvalidConfiguration

Value "${input}" is not valid for ${envName}. Should be lowe

Error message

Value "${input}" is not valid for ${envName}. Should be lower or equal than 65535.

What it means

asPortNumber throws InvalidConfiguration when the port value exceeds 65535, the maximum TCP/UDP port number. Cube validates port env vars eagerly so startup fails with a clear message instead of a later bind error. Callers include asPortOrSocket and asFalseOrPort.

Source

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

        return parseInt(input.slice(0, -2), 10) * 1024 * 1024;
      case 'gb':
        return parseInt(input.slice(0, -2), 10) * 1024 * 1024 * 1024;
      default: {
        throw new InvalidConfiguration(envName, input, description);
      }
    }
  }

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

export function asPortNumber(input: number, envName: string) {
  if (input < 0) {
    throw new InvalidConfiguration(envName, input, 'Should be a positive integer.');
  }

  if (input > 65535) {
    throw new InvalidConfiguration(envName, input, 'Should be lower or equal than 65535.');
  }

  return input;
}

/**
 * Determines whether multiple data sources were declared or not.
 */
function isMultipleDataSources(): boolean {
  // eslint-disable-next-line no-use-before-define
  return getEnv('dataSources').length > 0;
}

/**
 * Returns the specified data source if assertions are passed, throws
 * an error otherwise.
 * @param dataSource The data source to assert.
 */

View on GitHub (pinned to 7d981676b3)

Solutions

Set the env var to an integer in the range 0-65535 (e.g. 4000).
If you intended a large number as a size or count, put it in the correct env var for that purpose.
Double-check the digits in the .env value for typos.

Example fix

// before (.env)
CUBEJS_PORT=655360

// after (.env)
CUBEJS_PORT=65536 is invalid; use:
CUBEJS_PORT=4000

Defensive patterns

Strategy: validation

Validate before calling

const raw = Number(process.env.CUBEJS_PORT);
if (process.env.CUBEJS_PORT !== undefined && (raw > 65535 || !Number.isInteger(raw))) {
  throw new Error(`CUBEJS_PORT="${process.env.CUBEJS_PORT}" must be an integer <= 65535.`);
}

Type guard

function isValidPort(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 65535;
}

Try / catch

try {
  startCubeServer();
} catch (e) {
  if (e instanceof InvalidConfiguration && e.message.includes('65535')) {
    console.error('Port exceeds 65535; correct the value in your .env.');
    process.exit(1);
  }
  throw e;
}

Prevention

Verify port digits for typos (extra digit -> 655360 instead of 6553).
Never copy large numeric values (sizes, counts) into port variables.
Clamp or reject ports > 65535 in your deployment config validation.
Document valid port ranges next to each port env var in your ops runbook.

When it happens

Trigger: Setting a port env var (e.g. CUBEJS_PORT, CUBEJS_SQL_PORT) to a number above 65535, such as 65536 or 80800.

Common situations: Digit transposition or an extra digit typed in .env; confusing byte-size values with ports; copy-pasting values between differently-named variables.

Related errors

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