apache/druid · error · NotFoundException

Unknown schema %s

Error message

Unknown schema %s

What it means

CatalogResource.validateSchema() resolves the requested schema name against the catalog and returns 404 Not Found when no SchemaSpec matches. It is a request-level guard so that operations against a nonexistent schema (read or write) fail early with a clear message instead of a null-pointer deeper in the resource.

Source

Thrown at extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/http/CatalogResource.java:560

    }

    if (!schema.accepts(spec.type())) {
      throw CatalogException.badRequest(
          "Cannot create tables of type %s in schema %s",
          spec.type(),
          schema.name()
      );
    }
  }

  private SchemaSpec validateSchema(String schemaName, boolean forWrite) throws CatalogException
  {
    if (Strings.isNullOrEmpty(schemaName)) {
      throw CatalogException.badRequest("Schema name is required");
    }
    SchemaSpec schema = catalog.resolveSchema(schemaName);
    if (schema == null) {
      throw new NotFoundException("Unknown schema %s", schemaName);
    }

    if (forWrite && !schema.writable()) {
      throw CatalogException.badRequest(
          "Cannot modify schema %s",
          schemaName
      );
    }
    return schema;
  }

  private static ResourceAction resourceAction(SchemaSpec schema, String tableName, Action action)
  {
    return new ResourceAction(new Resource(tableName, schema.securityResource()), action);
  }

  private void authorizeTable(
      final SchemaSpec schema,

View on GitHub (pinned to 9b90983fd2)

Solutions

1. List the existing schemas (GET /druid-ext/v1/catalog/schemas or via the catalog view) and use an exact existing name.
2. Fix the schema name spelling/case in the request and retry.
3. Create/provision the schema first if it is supposed to exist, then re-run the operation.

Example fix

// before
curl .../catalog/tables?schema=DRUID_ARCHIVES

// after
curl .../catalog/schemas          # confirm available names
curl .../catalog/tables?schema=druid

const schemas = await fetch('/druid-ext/v1/catalog/schemas').then(r => r.json());
function schemaExists(name) {
  return schemas.some(s => s.name === name);
}
if (!schemaExists('druid')) throw new Error('schema not found');

try {
  const res = await fetch(url);
  if (res.status === 404) {
    const available = await fetch('/druid-ext/v1/catalog/schemas').then(r => r.json());
    throw new Error(`Schema not found; available: ${available.map(s => s.name)}`);
  }
} catch (e) { /* handle */ }

When it happens

Trigger: HTTP calls to /druid-ext/v1/catalog/... with a schemaName that does not exist in the catalog (e.g. GET/POST/DELETE on a misspelled or never-created schema).

Common situations: Typos in schema names in automation scripts ('DRUID' vs 'druid'); referring to a schema deleted by another operator; assuming the default 'druid' schema exists when catalog tables have never been provisioned.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Aggregation [%s] does not support column [%s] of type [%s].
• Cannot create table definitions in schema: %s
• BAD_STATE
• Tried to insert a duplicate table: %s
• Invalid Struct type.

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