alibaba/spring-ai-alibaba · error · RuntimeException

Failed to initialize table

Error message

Failed to initialize table

What it means

This is the catch-all branch of initializeTable(): SQLExceptions thrown while building the dialect-specific CREATE TABLE statement (during statement construction / metadata access inside the switch) are wrapped in this RuntimeException. It means table initialization failed before or during DDL preparation.

Solutions

1. Check the chained SQLException cause for the underlying database error.
2. Verify the DataSource connectivity and pool configuration at startup.
3. Ensure the JDBC driver version matches the database server version.
4. Retry initialization after restoring connectivity, or fail application startup with a clear message.

Example fix

// before
DatabaseStore store = new DatabaseStore(dataSource, ...); // throws at startup
// after
try {
    DatabaseStore store = new DatabaseStore(dataSource, ...);
} catch (RuntimeException e) {
    logger.error("Table init failed: {}", e.getCause(), e);
    throw e; // fail fast with logged cause
}

try (Connection c = dataSource.getConnection()) {
    if (!c.isValid(2)) throw new IllegalStateException("DataSource connection invalid at startup");
}

try { DatabaseStore s = new DatabaseStore(ds, ...); } catch (RuntimeException e) { log.error("init failed: {}", e.getCause(), e); throw new IllegalStateException("Store init failed", e); }

When it happens

Trigger: Constructing DatabaseStore when the dialect switch path throws SQLException (e.g., connection failure while preparing DDL, metadata access problems).

Common situations: Database unreachable at first use; driver-specific errors during statement preparation; connection pool exhausted at startup.

Related errors

• Unable to create tables
• Failed to clear database store
• Failed to get store size from database
• AccountNotFound
• APP_COMPONENT_LIST_ERROR

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/f4d36f3ce8d74775. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/DatabaseStore.java:787

                        + "namespace TEXT, " + "key_name VARCHAR(500), " + "value_json TEXT, "
                        + "created_at TIMESTAMP, " + "updated_at TIMESTAMP" + ")";
                case POSTGRESQL -> "CREATE TABLE IF NOT EXISTS " + tableName + " ("
                        + "pk_id BIGSERIAL PRIMARY KEY, "
                        + "id TEXT NOT NULL, "
                        + "id_hash CHAR(64) NOT NULL UNIQUE, "
                        + "namespace TEXT, " + "key_name VARCHAR(500), " + "value_json TEXT, "
                        + "created_at TIMESTAMP, " + "updated_at TIMESTAMP" + ")";
                case H2 -> "CREATE TABLE IF NOT EXISTS " + tableName + " ("
                        + "pk_id BIGINT AUTO_INCREMENT PRIMARY KEY, "
                        + "id TEXT NOT NULL, "
                        + "id_hash CHAR(64) NOT NULL UNIQUE, "
                        + "namespace TEXT, " + "key_name VARCHAR(500), " + "value_json TEXT, "
                        + "created_at TIMESTAMP, " + "updated_at TIMESTAMP" + ")";
                case OTHER -> throw new UnsupportedOperationException(
                        "Unsupported database dialect: " + dialect + ". Supported dialects: H2, MySQL, PostgreSQL, Oracle");
            };
        } catch (SQLException e) {
            throw new RuntimeException("Failed to initialize table", e);
        }

        if (!shouldCreate) {
            return;
        }

        try (Connection conn = dataSource.getConnection(); Statement stmt = conn.createStatement()) {
            stmt.executeUpdate(sql);
        } catch (SQLException e) {
            throw new RuntimeException("Failed to initialize table", e);
        }
    }

    /**
     * Check whether a table already exists in the current database schema/catalog.
     *
     * @param conn      JDBC connection
     * @param tableName target table name

View on GitHub (pinned to f82da0b50f)