apache/seatunnel · error · DatabendConnectorException

ILLEGAL_STATE

ILLEGAL_STATE

Error message

Databend catalog is not opened. Please call open() first.

What it means

Guard in DatabendCatalog that fires when a catalog operation is invoked before open() has been called. The catalog tracks an isOpened flag; all database/table operations require an established catalog lifecycle. This is an API misuse / lifecycle error, not a connectivity problem.

Solutions

1. Call catalog.open() (with proper Config) before invoking any catalog methods
2. Verify the framework/plugin lifecycle that should call open() on your behalf is running
3. Check that open() did not throw or get skipped due to earlier errors

Example fix

// before
DatabendCatalog catalog = new DatabendCatalog(readonlyConfig);
boolean exists = catalog.tableExists(tablePath);
// after
DatabendCatalog catalog = new DatabendCatalog(readonlyConfig);
catalog.open();
boolean exists = catalog.tableExists(tablePath);

if (!catalog.isOpen()) { catalog.open(); }

boolean usable(DatabendCatalog c) { return c.isOpen(); }

try {
    catalog.listTables(database);
} catch (DatabendConnectorException e) {
    if (e.getErrorCode() == DatabendConnectorErrorCode.ILLEGAL_STATE) {
        catalog.open();
    } else { throw e; }
}

When it happens

Trigger: Calling databaseExists, listDatabases, listTables, tableExists, getTable, or createTable on a DatabendCatalog instance that was constructed but never had open() invoked (or after a hypothetical close).

Common situations: Using the catalog directly in custom code without the framework's open lifecycle; instantiating the catalog in tests and calling methods immediately; calling catalog methods after open() failed silently earlier.

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

• CONNECT_FAILED
• DatabaseAlreadyExistException: catalogName, databaseName
• DatabaseNotExistException: catalogName, databaseName
• Failed to open Hive catalog
• TableAlreadyExistException: catalogName, tablePath

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/40a30ee6253cda46. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-databend/src/main/java/org/apache/seatunnel/connectors/seatunnel/databend/catalog/DatabendCatalog.java:515

                return LocalTimeType.LOCAL_DATE_TYPE;
            case "TIMESTAMP":
                return LocalTimeType.LOCAL_DATE_TIME_TYPE;
            case "VARBINARY":
            case "BINARY":
                return BasicType.BYTE_TYPE;
            default:
                log.warn("Unsupported Databend type: {}, fallback to STRING type", typeName);
                return BasicType.STRING_TYPE;
        }
    }

    private Connection getConnection() throws SQLException {
        return DatabendUtil.createConnection(this.readonlyConfig);
    }

    private void checkOpen() {
        if (!isOpened) {
            throw new DatabendConnectorException(
                    DatabendConnectorErrorCode.ILLEGAL_STATE,
                    "Databend catalog is not opened. Please call open() first.");
        }
    }
}

View on GitHub (pinned to cf67b549a7)