apache/druid · critical · ISE

SQLCatalogManager only works with SQL based metadata store a

Error message

SQLCatalogManager only works with SQL based metadata store at this time

What it means

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.

Source

Thrown at extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/storage/sql/SQLCatalogManager.java:85

  private static final String CREATION_TIME_COL = "creationTime";
  private static final String UPDATE_TIME_COL = "updateTime";
  private static final String STATE_COL = "state";
  private static final String TABLE_TYPE_COL = "tableType";
  private static final String PROPERTIES_COL = "properties";
  private static final String COLUMNS_COL = "columns";

  private final MetadataStorageManager metastoreManager;
  private final SQLMetadataConnector connector;
  private final ObjectMapper jsonMapper;
  private final IDBI dbi;
  private final String tableName;
  private final Deque<CatalogUpdateListener> listeners = new ConcurrentLinkedDeque<>();

  @Inject
  public SQLCatalogManager(MetadataStorageManager metastoreManager)
  {
    if (!metastoreManager.isSql()) {
      throw new ISE("SQLCatalogManager only works with SQL based metadata store at this time");
    }
    this.metastoreManager = metastoreManager;
    this.connector = metastoreManager.sqlConnector();
    this.dbi = connector.getDBI();
    this.jsonMapper = metastoreManager.jsonMapper();
    this.tableName = getTableDefnTable();
  }

  @Override
  @LifecycleStart
  public void start()
  {
    createTableDefnTable();
  }

  public static final String CREATE_TABLE =
      "CREATE TABLE %s (\n" +
      "  schemaName VARCHAR(255) NOT NULL,\n" +

View on GitHub (pinned to 9b90983fd2)

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.

Example fix

// before (derby/non-SQL metadata store with catalog loaded)
druid.extensions.loadList=["druid-catalog"]
druid.metadata.storage.type=derby

// after (SQL metastore)
druid.extensions.loadList=["druid-catalog","druid-postgresql-metadata"]
druid.metadata.storage.type=postgresql
druid.metadata.storage.connector.connectURI=jdbc:postgresql://db:5432/druid
druid.metadata.storage.connector.user=druid
druid.metadata.storage.connector.password=diurd

Defensive patterns

Strategy: validation

Validate before calling

if (!metastoreManager.isSql()) {
  throw new IllegalStateException("Configure a SQL metadata store (druid.metadata.storage.type=postgresql/mysql) before enabling the druid-catalog extension");
}

Prevention

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.

When it happens

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

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

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/8a161098f29559ba. Report an issue: GitHub.