cube-js/cube · error · TypeError

The ${keyByDataSource('CUBEJS_DB_PINOT_NULL_HANDLING', dataS

Error message

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

What it means

Env type validation in env.ts pinotNullHandling: CUBEJS_DB_PINOT_NULL_HANDLING is set to a value other than 'true' or 'false' (case-insensitive). The strict boolean check throws this TypeError when the Pinot driver resolves its null-handling flag, which toggles null value support in StarTree.

Source

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

    preAggregations,
  }: DataSourceOpts) => (
    get(keyByDataSource('CUBEJS_DB_PINOT_AUTH_TOKEN', dataSource, preAggregations)).asString()
  ),

  /**
   * Pinot / Startree Null value support
   */

  pinotNullHandling: ({ dataSource, preAggregations }: DataSourceOpts) => {
    const val = get(keyByDataSource('CUBEJS_DB_PINOT_NULL_HANDLING', dataSource, preAggregations)).asString();

    if (val) {
      if (val.toLocaleLowerCase() === 'true') {
        return true;
      } else if (val.toLowerCase() === 'false') {
        return false;
      } else {
        throw new TypeError(
          `The ${
            keyByDataSource(
              'CUBEJS_DB_PINOT_NULL_HANDLING',
              dataSource,
            )
          } must be either 'true' or 'false'.`
        );
      }
    } else {
      return false;
    }
  },

  /** ****************************************************************
   * Dremio Driver                                                   *
   ***************************************************************** */

  /**

View on GitHub (pinned to 7d981676b3)

Solutions

1. Set CUBEJS_DB_PINOT_NULL_HANDLING to 'true' or 'false' exactly.
2. Unset the variable to disable explicit null handling configuration.
3. Confirm the env value contains no trailing spaces or quotes.

When it happens

Trigger: Thrown at packages/cubejs-backend-shared/src/env.ts:1861 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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