apache/iceberg · error · IllegalArgumentException

Unsupported scope type for listIcebergTables

Error message

Unsupported scope type for listIcebergTables: %s

What it means

JdbcSnowflakeClient.listIcebergTables supports listing Iceberg tables only at ACCOUNT or SCHEMA scope; any other SnowflakeIdentifier.Type triggers an IllegalArgumentException before SQL execution. This is argument validation guarding the scope hierarchy expected by the listing API.

Solutions

1. Pass a SCHEMA-typed SnowflakeIdentifier (SnowflakeIdentifier.ofSchema(db, schema)) or the account root to listIcebergTables
2. Correct the namespace-to-identifier mapping in the calling code before invoking the client
3. Validate scope.type() at the call site and choose the proper listing method per level
4. Add unit tests covering listing at each supported scope type

Example fix

// before
client.listIcebergTables(SnowflakeIdentifier.ofDatabase("db")); // throws
// after
client.listIcebergTables(SnowflakeIdentifier.ofSchema("db", "my_schema"));

SnowflakeIdentifier.Type t = scope.type();
if (t != SnowflakeIdentifier.Type.ROOT && t != SnowflakeIdentifier.Type.SCHEMA) {
  throw new IllegalArgumentException("listIcebergTables requires ROOT or SCHEMA scope, got: " + t);
}

static boolean isTableListableScope(SnowflakeIdentifier s) {
  SnowflakeIdentifier.Type t = s.type();
  return t == SnowflakeIdentifier.Type.ROOT || t == SnowflakeIdentifier.Type.SCHEMA;
}

try {
  client.listIcebergTables(scope);
} catch (IllegalArgumentException e) {
  LOG.error("Bad scope for listIcebergTables: {}", scope);
  throw e;
}

When it happens

Trigger: Calling listIcebergTables with a scope typed DATABASE, TABLE, or COLUMN instead of ACCOUNT/ROOT or SCHEMA — e.g. passing a database-level identifier where the API expects a schema, or a generic adapter forwarding an unresolvable namespace.

Common situations: Caller confusion between Iceberg namespace levels and Snowflake identifier types, catalog adapters that map arbitrary namespace lengths to Snowflake scopes, or refactoring that changed expected hierarchy depth.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unsupported scope type for listSchemas
• Cannot bucket by type:
• Cannot convert identifier
• Cannot find table
• Cannot pass path based identifier to

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

Appendix: source

Thrown at snowflake/src/main/java/org/apache/iceberg/snowflake/JdbcSnowflakeClient.java:301

    StringBuilder baseQuery = new StringBuilder("SHOW ICEBERG TABLES");
    String[] queryParams = null;
    switch (scope.type()) {
      case ROOT:
        // account-level listing
        baseQuery.append(" IN ACCOUNT");
        break;
      case DATABASE:
        // database-level listing
        baseQuery.append(" IN DATABASE IDENTIFIER(?)");
        queryParams = new String[] {scope.toIdentifierString()};
        break;
      case SCHEMA:
        // schema-level listing
        baseQuery.append(" IN SCHEMA IDENTIFIER(?)");
        queryParams = new String[] {scope.toIdentifierString()};
        break;
      default:
        throw new IllegalArgumentException(
            String.format("Unsupported scope type for listIcebergTables: %s", scope));
    }

    final String finalQuery = baseQuery.toString();
    final String[] finalQueryParams = queryParams;
    List<SnowflakeIdentifier> tables;
    try {
      tables =
          connectionPool.run(
              conn ->
                  queryHarness.query(conn, finalQuery, TABLE_RESULT_SET_HANDLER, finalQueryParams));
    } catch (SQLException e) {
      throw snowflakeExceptionToIcebergException(
          scope, e, String.format("Failed to list tables for scope '%s'", scope));
    } catch (InterruptedException e) {
      throw new UncheckedInterruptedException(
          e, "Interrupted while listing tables for scope '%s'", scope);
    }

View on GitHub (pinned to 86d9c8fc54)