{"record":{"id":"c41719bec0c53d7c","repo":"cube-js/cube","slug":"sql-interface-is-not-initialized-please-enable-th","errorCode":null,"errorMessage":"SQL interface is not initialized. Please enable the SQL interface in your settings.","messagePattern":"SQL interface is not initialized\\. Please enable the SQL interface in your settings\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cubejs-api-gateway/src/sql-server.ts","lineNumber":73,"sourceCode":"\n    // Actually, proxy is enabled in gateway\n    // But passing port into registerInterface will start native gateway\n    if (getEnv('nativeApiGateway')) {\n      this.gatewayPort = options.gatewayPort || 7575;\n    }\n  }\n\n  public getNativeGatewayPort(): number {\n    if (this.gatewayPort) {\n      return this.gatewayPort;\n    }\n\n    throw new Error('Native api gateway is not enabled');\n  }\n\n  private getSqlInterfaceInstance(): SqlInterfaceInstance {\n    if (!this.sqlInterfaceInstance) {\n      throw new Error('SQL interface is not initialized. Please enable the SQL interface in your settings.');\n    }\n\n    return this.sqlInterfaceInstance;\n  }\n\n  public async execSql(sqlQuery: string, stream: any, securityContext?: any, cacheMode?: CacheMode, timezone?: string, throwContinueWait?: boolean, requestId?: string) {\n    await execSql(this.getSqlInterfaceInstance(), sqlQuery, stream, securityContext, cacheMode, timezone, throwContinueWait, requestId);\n  }\n\n  public async sql4sql(sqlQuery: string, disablePostProcessing: boolean, securityContext?: unknown): Promise<Sql4SqlResponse> {\n    return sql4sql(this.getSqlInterfaceInstance(), sqlQuery, disablePostProcessing, securityContext);\n  }\n\n  public async rest4sql(sqlQuery: string, securityContext?: unknown): Promise<QueryConvertResponse> {\n    return rest4sql(this.getSqlInterfaceInstance(), sqlQuery, securityContext);\n  }\n\n  protected buildCheckSqlAuth(options: SQLServerOptions): CheckSQLAuthFn {","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-api-gateway/src/sql-server.ts#L55-L91","documentation":"The SQL interface instance (registered via the Rust native layer) is only created when SQLServer.init() runs. getSqlInterfaceInstance guards execSql/sql4sql/rest4sql: if the native SQL interface was never registered, executing SQL throws 'SQL interface is not initialized. Please enable the SQL interface in your settings.' This means the SQL API surface is not available in this deployment.","triggerScenarios":"Calling execSql, sql4sql, or rest4sql on a SQLServer that has not had init() completed, or in a build/deployment where the SQL interface is disabled or the native module failed to register.","commonSituations":"Embedding cubejs-server-core with the SQL API disabled in settings while a custom route calls execSql; a failed native module registration earlier in boot silently leaving sqlInterfaceInstance null; calling SQL APIs during startup before init() resolves; stripped/minimal deployments (e.g. some serverless setups) that omit the native SQL interface.","solutions":["Enable the SQL interface in your Cube settings/deployment so init() registers the native interface at startup.","Ensure any call to execSql/sql4sql/rest4sql happens only after SQLServer.init() resolves.","Check startup logs for native module registration failures; fix the underlying @cubejs-backend/native load error.","If the SQL API is intentionally off, route the feature through the REST API instead of execSql."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (!sqlServerReady) {\n  throw new Error('SQLServer.init() has not completed; SQL API calls are unavailable');\n}","typeGuard":"function isSqlInterfaceAvailable(s: unknown): s is { execSql: Function } {\n  return typeof s === 'object' && s !== null && '__sqlInterfaceReady' in (s as any) === true;\n} // prefer an explicit readiness flag/boolean exposed by your wrapper","tryCatchPattern":"try {\n  await sqlServer.execSql(sql, stream, ctx);\n} catch (e) {\n  if (e.message.includes('SQL interface is not initialized')) {\n    console.error('Enable the SQL interface or await init() before issuing SQL');\n  } else throw e;\n}","preventionTips":["Always await SQLServer.init() before any execSql/sql4sql/rest4sql call.","Enable the SQL interface in Cube settings for deployments that need SQL API access.","Monitor startup logs for @cubejs-backend/native registration failures.","Do not attempt SQL API calls in deployments that intentionally omit the native SQL interface."],"tags":["sql-api","initialization","native"],"backgroundTag":"service-not-initialized","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}