apache/beam · error · UnsupportedOperationException

Entry doesn't have a schema. Please attach a schema to

Error message

Entry doesn't have a schema. Please attach a schema to '{tableName}' in Data Catalog: {entry}

What it means

After a successful DataCatalog lookup, toCalciteTable requires the entry to carry a column schema; entries with zero schema columns are rejected with UnsupportedOperationException telling the user to attach a schema to the entry in Data Catalog. Beam SQL cannot build a BeamSqlTable without column definitions.

Solutions

Attach a schema to the DataCatalog entry (console: entry > Attach schema, or DataCatalogClient.updateEntry/CloudSchema).
For BigQuery-backed entries, verify the BigQuery table has a defined schema and re-sync it into DataCatalog.
Confirm you are resolving the intended entry, not an empty one created by an earlier failed registration.

Example fix

// before
// DataCatalog entry 'my-proj:my_ds.t' created with no schema -> throws

// after
// attach schema before querying:
// dataCatalogClient.updateEntry(entryName, entry.toBuilder().setSchema(cloudSchema).build());

Defensive patterns

Strategy: validation

Validate before calling

Entry entry = dataCatalogClient.lookupEntry(
    LookupEntryRequest.newBuilder().setSqlResource(tableName).build());
if (entry.getSchema().getColumnsCount() == 0) {
  throw new IllegalStateException("Entry has no schema: " + tableName);
}

Try / catch

try {
  Table t = provider.getTable(tableName);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("doesn't have a schema")) {
    // attach schema to the entry, then retry
  }
}

Prevention

Attach a schema when creating DataCatalog entries, before running SQL
For BigQuery entries, ensure the table schema is synced into the catalog
Verify the resolved entry is the one that carries the schema (not an empty duplicate)

When it happens

Trigger: Looking up a DataCatalog entry that was registered without a schema (tag template only, schema never attached, or schema attached to a different entry/tag).

Common situations: Entries created programmatically without setting the CloudSchema, BigQuery tables whose schema was never synced into the catalog entry, or looking up the wrong entry version that predates schema attachment.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/2ab714e135d6218d. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/datacatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/datacatalog/DataCatalogTableProvider.java:191

                  .build());
      builder
          .updateEntrySettings()
          .setRetryableCodes(
              ImmutableSet.of(Code.PERMISSION_DENIED, Code.DEADLINE_EXCEEDED, Code.UNAVAILABLE))
          .setRetrySettings(
              builder.updateEntrySettings().getRetrySettings().toBuilder()
                  .setMaxRetryDelay(Duration.ofMinutes(1L))
                  .build());

      return DataCatalogClient.create(builder.build());
    } catch (IOException e) {
      throw new RuntimeException("Error creating Data Catalog client", e);
    }
  }

  private Table toCalciteTable(String tableName, Entry entry) {
    if (entry.getSchema().getColumnsCount() == 0) {
      throw new UnsupportedOperationException(
          "Entry doesn't have a schema. Please attach a schema to '"
              + tableName
              + "' in Data Catalog: "
              + entry.toString());
    }
    Schema schema = SchemaUtils.fromDataCatalog(entry.getSchema());

    Optional<Table.Builder> tableBuilder = tableFactory.tableBuilder(entry);
    if (!tableBuilder.isPresent()) {
      throw new UnsupportedOperationException(
          String.format(
              "Unsupported Data Catalog entry: %s",
              MoreObjects.toStringHelper(entry)
                  .add("linkedResource", entry.getLinkedResource())
                  .add("hasGcsFilesetSpec", entry.hasGcsFilesetSpec())
                  .toString()));
    }

View on GitHub (pinned to 12126d8942)