apache/iceberg · error · UnsupportedOperationException

Unknown catalog type:

Error message

Unknown catalog type: 

What it means

Thrown by CatalogUtil.buildIcebergCatalog when the catalog type property (iceberg.catalog.type / CatalogUtil.ICEBERG_CATALOG_TYPE) does not match any of the known built-in types (hive, hadoop, rest, glue, nessie, jdbc, bigquery). The type string cannot be mapped to a catalog implementation class, so an UnsupportedOperationException names the unknown value.

Source

Thrown at core/src/main/java/org/apache/iceberg/CatalogUtil.java:340

          catalogImpl = ICEBERG_CATALOG_HADOOP;
          break;
        case ICEBERG_CATALOG_TYPE_REST:
          catalogImpl = ICEBERG_CATALOG_REST;
          break;
        case ICEBERG_CATALOG_TYPE_GLUE:
          catalogImpl = ICEBERG_CATALOG_GLUE;
          break;
        case ICEBERG_CATALOG_TYPE_NESSIE:
          catalogImpl = ICEBERG_CATALOG_NESSIE;
          break;
        case ICEBERG_CATALOG_TYPE_JDBC:
          catalogImpl = ICEBERG_CATALOG_JDBC;
          break;
        case ICEBERG_CATALOG_TYPE_BIGQUERY:
          catalogImpl = ICEBERG_CATALOG_BIGQUERY;
          break;
        default:
          throw new UnsupportedOperationException("Unknown catalog type: " + catalogType);
      }
    } else {
      String catalogType = options.get(ICEBERG_CATALOG_TYPE);
      Preconditions.checkArgument(
          catalogType == null,
          "Cannot create catalog %s, both type and catalog-impl are set: type=%s, catalog-impl=%s",
          name,
          catalogType,
          catalogImpl);
    }

    return loadCatalog(catalogImpl, name, options, conf);
  }

  /**
   * Load a custom {@link FileIO} implementation.
   *
   * <p>The implementation must have a no-arg constructor. If the class implements Configurable, a

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set type to a supported value: hive, hadoop, rest, glue, nessie, jdbc, or bigquery (case-insensitive).
2. If the catalog is a custom implementation, remove type and set catalog-impl to the fully qualified class instead (type and catalog-impl cannot both be set).
3. Upgrade to an Iceberg version that supports the catalog type you need.
4. Trim/clean the config value to rule out stray whitespace or quoting from environment-based configuration.

Example fix

// before
Map<String, String> opts = Map.of("type", "postgres"); // unknown type
// after
Map<String, String> opts = Map.of("type", "jdbc", "uri", "jdbc:postgresql://host:5432/db");

private static final Set<String> KNOWN_TYPES = Set.of("hive","hadoop","rest","glue","nessie","jdbc","bigquery");
String type = options.getOrDefault("type", "hive").toLowerCase(Locale.ROOT);
if (!KNOWN_TYPES.contains(type)) {
  throw new IllegalArgumentException("Unknown catalog type: " + type);
}

static boolean isKnownCatalogType(String type) {
  return type == null || Set.of("hive","hadoop","rest","glue","nessie","jdbc","bigquery")
      .contains(type.toLowerCase(Locale.ROOT));
}

try {
  Catalog catalog = CatalogUtil.buildIcebergCatalog(name, options, conf);
} catch (UnsupportedOperationException e) {
  LOG.error("Unsupported catalog type '{}' - use one of hive,hadoop,rest,glue,nessie,jdbc,bigquery or set catalog-impl", e.getMessage());
  throw e;
}

When it happens

Trigger: Calling buildIcebergCatalog with options containing type=<value> where value is not one of the supported catalog types (case-insensitive), and no catalog-impl is provided; e.g. type=jdbc2, type=HadoopCatalog, or a misspelled type name.

Common situations: Typo in the type key value in Spark/Flink/Engine catalog config; using a catalog type added in a newer Iceberg version while running an older runtime; expecting a custom type string to resolve without also setting catalog-impl; stray whitespace or wrong casing handled only via toLowerCase, not trimming.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid distribution mode: %s
• Invalid file format: %s
• %s does not expose configuration properties
• Cannot find Dynamo catalog table %s
• Cannot support given S3 encryption type:

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/854de9469400dfbe. Report an issue: GitHub.