prestodb/presto · error · SemanticException

MISSING_CATALOG

MISSING_CATALOG

Error message

Catalog %s does not exist

What it means

MetadataUtils.getTableColumnMetadata resolves a table via the connector's metadata resolver. If no TableHandle is returned, it distinguishes why: when the catalog itself does not exist it throws SemanticException MISSING_CATALOG, naming the missing catalog. This gives precise diagnostics before falling through to schema/table checks.

Source

Thrown at presto-main-base/src/main/java/com/facebook/presto/util/MetadataUtils.java:87

    {
        if (metadataHandle.isPreProcessMetadataCalls()) {
            return metadataHandle.getMaterializedViewDefinition(viewName);
        }

        return session.getRuntimeStats().recordWallTime(
                GET_MATERIALIZED_VIEW_TIME_NANOS,
                () -> metadataResolver.getMaterializedView(viewName));
    }

    public static TableColumnMetadata getTableColumnMetadata(Session session, MetadataResolver metadataResolver, QualifiedObjectName tableName)
    {
        Optional<TableHandle> tableHandle = session.getRuntimeStats().recordWallTime(
                GET_TABLE_HANDLE_TIME_NANOS,
                () -> metadataResolver.getTableHandle(tableName));

        if (!tableHandle.isPresent()) {
            if (!metadataResolver.catalogExists(tableName.getCatalogName())) {
                throw new SemanticException(MISSING_CATALOG, "Catalog %s does not exist", tableName.getCatalogName());
            }
            if (!metadataResolver.schemaExists(new CatalogSchemaName(tableName.getCatalogName(), tableName.getSchemaName()))) {
                throw new SemanticException(MISSING_SCHEMA, "Schema %s does not exist", tableName.getSchemaName());
            }
            throw new SemanticException(MISSING_TABLE, "Table %s does not exist", tableName);
        }

        Map<String, ColumnHandle> columnHandles = session.getRuntimeStats().recordWallTime(
                GET_COLUMN_HANDLE_TIME_NANOS,
                () -> metadataResolver.getColumnHandles(tableHandle.get()));

        List<ColumnMetadata> columnsMetadata = session.getRuntimeStats().recordWallTime(
                GET_COLUMN_METADATA_TIME_NANOS,
                () -> metadataResolver.getColumns(tableHandle.get()));

        return new TableColumnMetadata(tableHandle, columnHandles, columnsMetadata);
    }
}

View on GitHub (pinned to 55bb57d202)

Solutions

  1. Verify the catalog exists: SHOW CATALOGS, and check etc/catalog/<name>.properties on the coordinator
  2. Correct the catalog name in the query
  3. Add/configure the missing connector catalog and restart the server
  4. Fully qualify the table as catalog.schema.table

Example fix

// before
SELECT * FROM prod-db.sales.orders; -- catalog 'prod-db' not configured
// after
SELECT * FROM postgresql.sales.orders; -- catalog 'postgresql' configured in etc/catalog/postgresql.properties
Defensive patterns

Strategy: try-catch

Validate before calling

// Check catalog existence before resolving table metadata
if (!metadata.listCatalogs(session).contains(tableName.getCatalogName())) {
    throw new IllegalArgumentException("Catalog not found: " + tableName.getCatalogName());
}

Try / catch

try {
    columns = MetadataUtils.getTableColumnMetadata(...);
} catch (SemanticException e) {
    if (e.getCode() == MISSING_CATALOG) {
        throw new UserError("Unknown catalog: check etc/catalog configuration");
    }
    throw e;
}

Prevention

When it happens

Trigger: Querying or fetching column metadata for a fully qualified table name whose catalog prefix is not registered, e.g. SELECT * FROM myschema.mytable where 'myschema' is being treated as a nonexistent catalog, or SHOW COLUMNS FROM badcatalog.s.t.

Common situations: Typo in catalog name; catalog connector not configured in etc/catalog/*.properties; connector failed to load at startup; using a two-part name that resolves catalog incorrectly.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/d9b55b55f0b3e657. Report an issue: GitHub.