cube-js/cube · error · Error

Unable to connect to your Pinot instance

Error message

Unable to connect to your Pinot instance

What it means

PinotDriver.testConnection runs `select 1` via the broker; if the HTTP response returns an empty array, the driver concludes it cannot reach a working Pinot instance and throws this error. An empty result from the health query means the broker responded without usable data or via an unexpected path.

Source

Thrown at packages/cubejs-pinot-driver/src/PinotDriver.ts:139

    };

    const useSsl = getEnv('dbSsl', { dataSource, preAggregations });
    const rawHost = this.config.host || '';
    const host = /^https?:\/\//i.test(rawHost)
      ? rawHost
      : `${useSsl ? 'https' : 'http'}://${rawHost}`;
    this.url = `${host}:${this.config.port}/query/sql`;
  }

  public readOnly(): boolean {
    return true;
  }

  public testConnection() {
    return (<Promise<any[]>> this.queryPromised('select 1'))
      .then(response => {
        if (response.length === 0) {
          throw new Error('Unable to connect to your Pinot instance');
        }
      });
  }

  public query(query: string, values: unknown[]): Promise<any[]> {
    return <Promise<any[]>> this.queryPromised(this.prepareQueryWithParams(query, values));
  }

  protected prepareQueryWithParams(query: string, values: unknown[]) {
    return formatAnsi(query, values || []);
  }

  public authorizationHeaders(): AuthorizationHeaders | {} {
    if (this.config.authToken) {
      const res: AuthorizationHeaders = { Authorization: `Bearer ${this.config.authToken}` };

      if (this.config.database) {
        res.database = this.config.database;

View on GitHub (pinned to 7d981676b3)

Solutions

1. Verify the broker host/port configuration (CUBEJS_DB_HOST / PORT) points to a Pinot broker, not the controller.
2. Confirm at least one table exists and is loaded in Pinot (query the controller API).
3. Test the broker manually with curl: POST the SQL API with 'select 1' and inspect the response.
4. Check authentication/TLS settings if the broker sits behind a gateway.

Example fix

// before
new PinotDriver({ host: 'http://pinot-controller:9000' });
// after
new PinotDriver({ host: 'http://pinot-broker:8099' });

// before instantiating, check the broker responds to the SQL API
const res = await fetch(`${host}/query/sql`, { method: 'POST', body: JSON.stringify({ sql: 'select 1' }) });
const body = await res.json();
if (!body || !body.resultTable) throw new Error('Pinot broker did not return usable data');

try {
  await driver.testConnection();
} catch (e) {
  if (e.message.includes('Unable to connect to your Pinot instance')) {
    console.error('Check broker URL/port and that at least one table is loaded');
  }
  throw e;
}

When it happens

Trigger: Calling `testConnection()` when `queryPromised('select 1')` resolves to an empty array — e.g., querying a non-existent table, a broker with no tables configured, or a misconfigured host/path that returns an empty successful response.

Common situations: Wrong broker URL or port (pointing at controller instead of broker); Pinot instance with no tables loaded; network proxy returning empty 200 responses; missing default table for `select 1` routing.

Related errors

• A user-defined contextToApiScopes function returns an incons
• A user-defined contextToApiScopes function returns a wrong s
• Unload is not configured. Please define CUBEJS_AWS_S3_OUTPUT
• Export bucket is not configured.
• Auth isn't set

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