cube-js/cube · error

SQL interface is not initialized. Please enable the SQL inte

Error message

SQL interface is not initialized. Please enable the SQL interface in your settings.

What it means

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.

Source

Thrown at packages/cubejs-api-gateway/src/sql-server.ts:73

    // Actually, proxy is enabled in gateway
    // But passing port into registerInterface will start native gateway
    if (getEnv('nativeApiGateway')) {
      this.gatewayPort = options.gatewayPort || 7575;
    }
  }

  public getNativeGatewayPort(): number {
    if (this.gatewayPort) {
      return this.gatewayPort;
    }

    throw new Error('Native api gateway is not enabled');
  }

  private getSqlInterfaceInstance(): SqlInterfaceInstance {
    if (!this.sqlInterfaceInstance) {
      throw new Error('SQL interface is not initialized. Please enable the SQL interface in your settings.');
    }

    return this.sqlInterfaceInstance;
  }

  public async execSql(sqlQuery: string, stream: any, securityContext?: any, cacheMode?: CacheMode, timezone?: string, throwContinueWait?: boolean, requestId?: string) {
    await execSql(this.getSqlInterfaceInstance(), sqlQuery, stream, securityContext, cacheMode, timezone, throwContinueWait, requestId);
  }

  public async sql4sql(sqlQuery: string, disablePostProcessing: boolean, securityContext?: unknown): Promise<Sql4SqlResponse> {
    return sql4sql(this.getSqlInterfaceInstance(), sqlQuery, disablePostProcessing, securityContext);
  }

  public async rest4sql(sqlQuery: string, securityContext?: unknown): Promise<QueryConvertResponse> {
    return rest4sql(this.getSqlInterfaceInstance(), sqlQuery, securityContext);
  }

  protected buildCheckSqlAuth(options: SQLServerOptions): CheckSQLAuthFn {

View on GitHub (pinned to 7d981676b3)

Solutions

1. Enable the SQL interface in your Cube settings/deployment so init() registers the native interface at startup.
2. Ensure any call to execSql/sql4sql/rest4sql happens only after SQLServer.init() resolves.
3. Check startup logs for native module registration failures; fix the underlying @cubejs-backend/native load error.
4. If the SQL API is intentionally off, route the feature through the REST API instead of execSql.

if (!sqlServerReady) {
  throw new Error('SQLServer.init() has not completed; SQL API calls are unavailable');
}

function isSqlInterfaceAvailable(s: unknown): s is { execSql: Function } {
  return typeof s === 'object' && s !== null && '__sqlInterfaceReady' in (s as any) === true;
} // prefer an explicit readiness flag/boolean exposed by your wrapper

try {
  await sqlServer.execSql(sql, stream, ctx);
} catch (e) {
  if (e.message.includes('SQL interface is not initialized')) {
    console.error('Enable the SQL interface or await init() before issuing SQL');
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Expressions are not allowed in this context
• Unexpected input parameter value '${payload.input}'
• Unexpected output parameter value '${payload.output}'
• query parameter must be a non-empty string
• Argument options must be an object

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