cube-js/cube · error · TypeError

The ${keyByDataSource('CUBEJS_DB_USE_SELECT_TEST_CONNECTION'

Error message

The ${keyByDataSource('CUBEJS_DB_USE_SELECT_TEST_CONNECTION', dataSource)} must be either 'true' or 'false'.

What it means

CUBEJS_DB_USE_SELECT_TEST_CONNECTION toggles using a SELECT 1 query for connection health checks, and Cube only accepts 'true' or 'false'; any other value throws a TypeError with the data-source-specific variable name interpolated.

Source

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

  ),

  /**
   * Use `SELECT 1` query for testConnection.
   * It might be used in any driver where there is a specific testConnection
   * like a REST call, but for some reason it's not possible to use it in
   * deployment environment.
   */
  dbUseSelectTestConnection: ({
    dataSource,
    preAggregations,
  }: DataSourceOpts) => {
    const val = get(keyByDataSource('CUBEJS_DB_USE_SELECT_TEST_CONNECTION', dataSource, preAggregations)).default('false').asString();
    if (val.toLocaleLowerCase() === 'true') {
      return true;
    } else if (val.toLowerCase() === 'false') {
      return false;
    } else {
      throw new TypeError(
        `The ${
          keyByDataSource('CUBEJS_DB_USE_SELECT_TEST_CONNECTION', dataSource)
        } must be either 'true' or 'false'.`
      );
    }
  },

  /**
   * Kafka host for direct downloads from ksqlDb
   */
  dbKafkaHost: ({ dataSource, preAggregations }: DataSourceOpts) => (
    get(keyByDataSource('CUBEJS_DB_KAFKA_HOST', dataSource, preAggregations)).asString()
  ),

  /**
   * Kafka user for direct downloads from ksqlDb
   */
  dbKafkaUser: ({ dataSource, preAggregations }: DataSourceOpts) => (

View on GitHub (pinned to 7d981676b3)

Solutions

1. Set the variable to exactly true or false.
2. Check the .env file for surrounding quotes and remove them.
3. Normalize the value in deployment scripts (e.g. ${VAR,,} lowercase and trimmed in bash).
4. Confirm with node -p "process.env.CUBEJS_DB_USE_SELECT_TEST_CONNECTION" in the container.

Example fix

// before
CUBEJS_DB_USE_SELECT_TEST_CONNECTION=yes
// after
CUBEJS_DB_USE_SELECT_TEST_CONNECTION=true

const v = process.env.CUBEJS_DB_USE_SELECT_TEST_CONNECTION;
if (v !== undefined && !/^(true|false)$/i.test(v.trim()))
  throw new Error(`CUBEJS_DB_USE_SELECT_TEST_CONNECTION must be 'true' or 'false', got: ${JSON.stringify(v)}`);

try {
  useSelectForTestConnection(dataSource);
} catch (e) {
  if (e instanceof TypeError && e.message.includes('USE_SELECT_TEST_CONNECTION')) {
    console.error('Set CUBEJS_DB_USE_SELECT_TEST_CONNECTION to true or false');
  }
  throw e;
}

When it happens

Trigger: Setting CUBEJS_DB_USE_SELECT_TEST_CONNECTION (or CUBEJS_DS_<DS>_USE_SELECT_TEST_CONNECTION) to '1', 'True ' with trailing space, 'YES', or a quoted '"true"' string.

Common situations: Copy-pasting toggle values from other frameworks that accept yes/1/on; misconfigured .env parsing that keeps quotes; typos like 'ture'.

Related errors

• Value "${value}" is not valid for CUBEJS_MAX_REQUEST_SIZE. M
• The ${keyByDataSource('CUBEJS_DB_SSL', dataSource)} must be
• The ${keyByDataSource('CUBEJS_DB_SSL_REJECT_UNAUTHORIZED', d
• wrong configuration for environment variable '{}' with '{}'
• wrong configuration for environment variable '{}' with '{}'

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