apache/beam · error · IllegalStateException

Beam JDBC connection has not been initialized

Error message

Beam JDBC connection has not been initialized

What it means

BeamCalciteSchemaFactory's inner Schema implementation is a placeholder that only works after the JDBC connection has been initialized. Every metadata method (getTable, getType, functions, etc.) calls illegal(), which throws IllegalStateException until initialization occurs.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/BeamCalciteSchemaFactory.java:228

    @Override
    public Expression getExpression(@Nullable SchemaPlus parentSchema, String name) {
      return illegal();
    }

    @Override
    public boolean isMutable() {
      return illegal();
    }

    @Override
    public Schema snapshot(SchemaVersion version) {
      return illegal();
    }

    @SuppressWarnings("TypeParameterUnusedInFormals")
    private static <T> T illegal() {
      throw new IllegalStateException("Beam JDBC connection has not been initialized");
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Initialize the connection first: execute a statement or use the documented init path before touching the schema
2. Obtain schema metadata through standard JDBC DatabaseMetaData instead of the internal Schema object
3. Ensure you are using a Beam JDBC connection wired through BeamSqlEnv, not an unconstructed default instance

Example fix

// before
Schema schema = ((BeamCalciteConnection) conn).getRootSchema();
schema.getTableNames(); // throws
// after
try (Statement stmt = conn.createStatement()) {
  stmt.executeQuery("SELECT 1"); // initializes the connection
}
// then access schema metadata

boolean initialized = false; // set true after first successful statement execution

try { schema.getTableNames(); } catch (IllegalStateException e) { initializeConnection(); schema.getTableNames(); }

When it happens

Trigger: Using a BeamCalciteConnection's schema object before executing a statement or completing connection initialization, e.g. calling connection.getRootSchema().getTable(...) or schema.getTableNames() on a fresh Beam JDBC connection.

Common situations: Inspection code that grabs the schema right after DriverManager.getConnection but before running a query, frameworks probing schema metadata early, tests using the raw schema object.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Unable to parse statement
• Failed to infer Beam schema
• Unable to create prepared statement for type: ${type}
• Unable run pipeline with EMPTY disposition.
• Unable run pipeline with CREATE IF NEEDED disposition.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/79350b91aac42261. Report an issue: GitHub.