apache/iceberg · error · java.lang.UnsupportedOperationException

Unknown catalog-type: %s (Must be 'hive', 'hadoop' or 'rest'

Error message

Unknown catalog-type: %s (Must be 'hive', 'hadoop' or 'rest')

What it means

FlinkCatalogFactory.createCatalogLoader selects a CatalogLoader based on the 'catalog-type' property, which must be 'hive', 'hadoop' or 'rest'. If the configured value matches none of the known constants, the switch falls through to default and throws UnsupportedOperationException. It is a configuration error indicating a mistyped or unsupported catalog-type value.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalogFactory.java:119

    String catalogType = properties.getOrDefault(ICEBERG_CATALOG_TYPE, ICEBERG_CATALOG_TYPE_HIVE);
    switch (catalogType.toLowerCase(Locale.ROOT)) {
      case ICEBERG_CATALOG_TYPE_HIVE:
        // The values of properties 'uri', 'warehouse', 'hive-conf-dir' are allowed to be null, in
        // that case it will
        // fallback to parse those values from hadoop configuration which is loaded from classpath.
        String hiveConfDir = properties.get(HIVE_CONF_DIR);
        String hadoopConfDir = properties.get(HADOOP_CONF_DIR);
        Configuration newHadoopConf = mergeHiveConf(hadoopConf, hiveConfDir, hadoopConfDir);
        return CatalogLoader.hive(name, newHadoopConf, properties);

      case ICEBERG_CATALOG_TYPE_HADOOP:
        return CatalogLoader.hadoop(name, hadoopConf, properties);

      case ICEBERG_CATALOG_TYPE_REST:
        return CatalogLoader.rest(name, hadoopConf, properties);

      default:
        throw new UnsupportedOperationException(
            "Unknown catalog-type: " + catalogType + " (Must be 'hive', 'hadoop' or 'rest')");
    }
  }

  @Override
  public String factoryIdentifier() {
    return FACTORY_IDENTIFIER;
  }

  @Override
  public Set<ConfigOption<?>> requiredOptions() {
    return ImmutableSet.<ConfigOption<?>>builder().build();
  }

  @Override
  public Set<ConfigOption<?>> optionalOptions() {
    return ImmutableSet.<ConfigOption<?>>builder().build();
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Set 'catalog-type' to exactly one of 'hive', 'hadoop' or 'rest' (lowercase).
  2. Check the concrete value with a log/print of the properties passed to the factory; fix the typo.
  3. If you need a catalog type not in this list (e.g. jdbc/nessie), use a Flink/Iceberg version that supports it or a custom CatalogLoader — this factory only supports the three.

Example fix

// before
CREATE CATALOG iceberg WITH ('type'='iceberg', 'catalog-type'='nessie');
// after
CREATE CATALOG iceberg WITH ('type'='iceberg', 'catalog-type'='rest', 'uri'='http://nessie:19120/api/v2');
Defensive patterns

Strategy: validation

Validate before calling

java.util.Set<String> supported = java.util.Set.of("hive", "hadoop", "rest");
String type = options.get("catalog-type");
if (type == null || !supported.contains(type)) {
  throw new IllegalArgumentException("catalog-type must be hive|hadop... actually one of " + supported + ", got: " + type);
}

Prevention

When it happens

Trigger: Setting the Flink table/DDL option 'catalog-type' (or CatalogProperties ICEBERG_CATALOG_TYPE) to any value other than 'hive', 'hadoop' or 'rest' — e.g. a typo like 'hdfs', 'jdbc', 'nessie', or wrong casing — when calling createCatalogLoader via catalogLoader.

Common situations: Copying a catalog config from another engine that supports more catalog types (jdbc, nessie); typos in the CREATE CATALOG ... WITH ('catalog-type'='...') clause; assuming case-insensitive values like 'Hive'.

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

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