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 only supports catalog types 'hive', 'hadoop' and 'rest' via the type.catalog property. When the configured catalog type does not match any known switch case, createCatalogLoader throws UnsupportedOperationException with this message. It indicates a misconfigured catalog factory property.

Source

Thrown at flink/v1.20/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 Map<String, String> requiredContext() {
    Map<String, String> context = Maps.newHashMap();
    context.put(TYPE, "iceberg");
    context.put(PROPERTY_VERSION, "1");
    return context;
  }

  @Override
  public List<String> supportedProperties() {
    return ImmutableList.of("*");
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Set 'type.catalog' to exactly one of: hive, hadoop, rest (lowercase).
  2. If you need a JDBC or other catalog type, use the appropriate Iceberg Flink version/build that supports it or construct a CatalogLoader programmatically instead of via FlinkCatalogFactory.
  3. Double-check you are passing the property in the WITH (...) options of the Flink CREATE CATALOG statement or factory config map.

Example fix

// before
CREATE CATALOG iceberg WITH ('type'='iceberg', 'type.catalog'='Hadoop');
// after
CREATE CATALOG iceberg WITH ('type'='iceberg', 'type.catalog'='hadoop');
Defensive patterns

Strategy: validation

Validate before calling

String type = options.get("type.catalog");
if (!Set.of("hive", "hadoop", "rest").contains(type)) {
  throw new IllegalArgumentException("type.catalog must be hive, hadoop or rest, got: " + type);
}

Type guard

null

Try / catch

try {
  catalogLoader = factory.createCatalogLoader(name, hadoopConf, options);
} catch (UnsupportedOperationException e) {
  LOG.error("Invalid type.catalog option: {}", e.getMessage());
  throw e;
}

Prevention

When it happens

Trigger: Setting catalog property 'type.catalog' (or 'catalog-type' depending on version) to a value other than hive/hadoop/rest — e.g. a typo like 'Hadoop', 'jdbc' in a Flink SQL client where JDBC isn't wired, or an empty/unset value mapping to a wrong branch.

Common situations: Typo in Flink SQL client YAML/DDL WITH options; using a catalog type available in other Iceberg integrations but not this Flink factory; case mismatch since the lookup is case-sensitive.

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/e674ca320df202f8. Report an issue: GitHub.