{"record":{"id":"ed5889dd7ab1b86c","repo":"cube-js/cube","slug":"unable-to-connect-to-your-pinot-instance","errorCode":null,"errorMessage":"Unable to connect to your Pinot instance","messagePattern":"Unable to connect to your Pinot instance","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cubejs-pinot-driver/src/PinotDriver.ts","lineNumber":139,"sourceCode":"    };\n\n    const useSsl = getEnv('dbSsl', { dataSource, preAggregations });\n    const rawHost = this.config.host || '';\n    const host = /^https?:\\/\\//i.test(rawHost)\n      ? rawHost\n      : `${useSsl ? 'https' : 'http'}://${rawHost}`;\n    this.url = `${host}:${this.config.port}/query/sql`;\n  }\n\n  public readOnly(): boolean {\n    return true;\n  }\n\n  public testConnection() {\n    return (<Promise<any[]>> this.queryPromised('select 1'))\n      .then(response => {\n        if (response.length === 0) {\n          throw new Error('Unable to connect to your Pinot instance');\n        }\n      });\n  }\n\n  public query(query: string, values: unknown[]): Promise<any[]> {\n    return <Promise<any[]>> this.queryPromised(this.prepareQueryWithParams(query, values));\n  }\n\n  protected prepareQueryWithParams(query: string, values: unknown[]) {\n    return formatAnsi(query, values || []);\n  }\n\n  public authorizationHeaders(): AuthorizationHeaders | {} {\n    if (this.config.authToken) {\n      const res: AuthorizationHeaders = { Authorization: `Bearer ${this.config.authToken}` };\n\n      if (this.config.database) {\n        res.database = this.config.database;","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-pinot-driver/src/PinotDriver.ts#L121-L157","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the broker host/port configuration (CUBEJS_DB_HOST / PORT) points to a Pinot broker, not the controller.","Confirm at least one table exists and is loaded in Pinot (query the controller API).","Test the broker manually with curl: POST the SQL API with 'select 1' and inspect the response.","Check authentication/TLS settings if the broker sits behind a gateway."],"exampleFix":"// before\nnew PinotDriver({ host: 'http://pinot-controller:9000' });\n// after\nnew PinotDriver({ host: 'http://pinot-broker:8099' });","handlingStrategy":"try-catch","validationCode":"// before instantiating, check the broker responds to the SQL API\nconst res = await fetch(`${host}/query/sql`, { method: 'POST', body: JSON.stringify({ sql: 'select 1' }) });\nconst body = await res.json();\nif (!body || !body.resultTable) throw new Error('Pinot broker did not return usable data');","typeGuard":null,"tryCatchPattern":"try {\n  await driver.testConnection();\n} catch (e) {\n  if (e.message.includes('Unable to connect to your Pinot instance')) {\n    console.error('Check broker URL/port and that at least one table is loaded');\n  }\n  throw e;\n}","preventionTips":["Point config at a Pinot broker (default port 8099), not the controller (9000).","Ensure at least one table exists before wiring Cube.","Smoke-test the broker SQL API with curl during setup.","Verify proxy/gateway behavior for empty 200 responses."],"tags":["pinot","connectivity","health-check","configuration"],"backgroundTag":"database-connection-failed","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}