{"record":{"id":"8a161098f29559ba","repo":"apache/druid","slug":"sqlcatalogmanager-only-works-with-sql-based-metada","errorCode":null,"errorMessage":"SQLCatalogManager only works with SQL based metadata store at this time","messagePattern":"SQLCatalogManager only works with SQL based metadata store at this time","errorType":"exception","errorClass":"ISE","httpStatus":null,"severity":"critical","filePath":"extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/storage/sql/SQLCatalogManager.java","lineNumber":85,"sourceCode":"  private static final String CREATION_TIME_COL = \"creationTime\";\n  private static final String UPDATE_TIME_COL = \"updateTime\";\n  private static final String STATE_COL = \"state\";\n  private static final String TABLE_TYPE_COL = \"tableType\";\n  private static final String PROPERTIES_COL = \"properties\";\n  private static final String COLUMNS_COL = \"columns\";\n\n  private final MetadataStorageManager metastoreManager;\n  private final SQLMetadataConnector connector;\n  private final ObjectMapper jsonMapper;\n  private final IDBI dbi;\n  private final String tableName;\n  private final Deque<CatalogUpdateListener> listeners = new ConcurrentLinkedDeque<>();\n\n  @Inject\n  public SQLCatalogManager(MetadataStorageManager metastoreManager)\n  {\n    if (!metastoreManager.isSql()) {\n      throw new ISE(\"SQLCatalogManager only works with SQL based metadata store at this time\");\n    }\n    this.metastoreManager = metastoreManager;\n    this.connector = metastoreManager.sqlConnector();\n    this.dbi = connector.getDBI();\n    this.jsonMapper = metastoreManager.jsonMapper();\n    this.tableName = getTableDefnTable();\n  }\n\n  @Override\n  @LifecycleStart\n  public void start()\n  {\n    createTableDefnTable();\n  }\n\n  public static final String CREATE_TABLE =\n      \"CREATE TABLE %s (\\n\" +\n      \"  schemaName VARCHAR(255) NOT NULL,\\n\" +","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/storage/sql/SQLCatalogManager.java#L67-L103","documentation":"SQLCatalogManager stores the Druid catalog in a SQL metadata store. At construction (via @Inject) it checks MetadataStorageManager.isSql(); if the cluster is configured with a non-SQL metadata store (e.g. Derby is absent or a non-SQL storage type), it fails fast with this ISE because only SQL-backed metastores are supported. The extension simply cannot function without a JDBC metadata store.","triggerScenarios":"DI creates SQLCatalogManager when the catalog extension is loaded while MetadataStorageManager.isSql() returns false — i.e. druid.metadata.storage.type is not a SQL connector type, or the node lacks the SQL metadata storage extension/configuration.","commonSituations":"Running a catalog-enabled cluster on a metadata store that is not SQL-based; forgetting to configure druid.metadata.storage.* on a node loading the druid-catalog extension; historical/derby-only single-node setups enabling the catalog.","solutions":["Set druid.metadata.storage.type to a SQL connector (e.g. postgresql or mysql) and configure druid.metadata.storage.connector.* JDBC properties.","Load the metadata storage extension for the chosen SQL store (druid.metadata.storage.type must be in extensions.load list), e.g. druid-postgresql-metadata.","If you don't need the catalog, remove the druid-catalog extension from druid.extensions.loadList on that node.","Verify the metadata store actually runs: the SQL DB must be reachable before services start."],"exampleFix":"// before (derby/non-SQL metadata store with catalog loaded)\ndruid.extensions.loadList=[\"druid-catalog\"]\ndruid.metadata.storage.type=derby\n\n// after (SQL metastore)\ndruid.extensions.loadList=[\"druid-catalog\",\"druid-postgresql-metadata\"]\ndruid.metadata.storage.type=postgresql\ndruid.metadata.storage.connector.connectURI=jdbc:postgresql://db:5432/druid\ndruid.metadata.storage.connector.user=druid\ndruid.metadata.storage.connector.password=diurd","handlingStrategy":"validation","validationCode":"if (!metastoreManager.isSql()) {\n  throw new IllegalStateException(\"Configure a SQL metadata store (druid.metadata.storage.type=postgresql/mysql) before enabling the druid-catalog extension\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only load the druid-catalog extension on clusters with a SQL metadata storage type.","Validate druid.metadata.storage.type and connector properties in your deployment config checks before startup.","Keep extension list and metadata store config in the same reviewed configuration template."],"tags":["configuration","metadata-store","startup"],"backgroundTag":"unsupported-operation","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}