cube-js/cube · error · InvalidConfiguration

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

Error message

Value "${input}" is not valid for ${envName}. Should be a positive integer.

What it means

asPortNumber validates port-typed env variables and throws InvalidConfiguration when the value is negative. The message says 'Should be a positive integer.' Port numbers must be 0-65535, so Cube rejects out-of-range values at startup rather than binding a nonsensical port. Callers include asPortOrSocket and asFalseOrPort.

Source

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

    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':
        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;
}

/**

View on GitHub (pinned to 7d981676b3)

Solutions

Set the env var to an integer between 0 and 65535 (e.g. 4000).
If you meant to disable the port-based feature, use the documented alternative (e.g. CUBEJS_SQL_PORT=false via asFalseOrPort) instead of a negative number.
Check for stray minus signs or corrupted values in the .env file.

Example fix

// before (.env)
CUBEJS_PORT=-4000

// after (.env)
CUBEJS_PORT=4000

Defensive patterns

Strategy: validation

Validate before calling

const raw = Number(process.env.CUBEJS_PORT);
if (process.env.CUBEJS_PORT !== undefined && !(Number.isInteger(raw) && raw >= 0 && raw <= 65535)) {
  throw new Error(`CUBEJS_PORT="${process.env.CUBEJS_PORT}" must be an integer 0-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('Should be a positive integer')) {
    console.error('Port env var must be >= 0; to disable the feature use the documented false sentinel.');
    process.exit(1);
  }
  throw e;
}

Prevention

Never use negative values for port env vars.
Use the documented sentinel (e.g. false) to disable a port-based feature, not -1.
Range-check ports 0-65535 in your config validation script.
Watch for templating mistakes that inject negative or placeholder values.

When it happens

Trigger: Setting a port env var (e.g. CUBEJS_PORT or CUBEJS_SQL_PORT) to a negative number like -1 or -8080, or to a value that resolves to a negative number.

Common situations: Sign/typo mistakes in .env files; templated configs where a placeholder was replaced with a negative or malformed value; disabling a port by trying a negative value instead of the documented sentinel (e.g. false).

Related errors

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