apache/iceberg · error · IllegalArgumentException

Unsupported scope type for listSchemas

Error message

Unsupported scope type for listSchemas: %s

What it means

JdbcSnowflakeClient.listSchemas only supports scoping the listing at ACCOUNT or DATABASE level; any other SnowflakeIdentifier.Type passed as scope triggers an IllegalArgumentException. It is an input-validation guard on the scope argument, thrown before any SQL is executed.

Solutions

1. Pass SnowflakeIdentifier.ofRoot() (account scope) or a DATABASE-typed identifier to listSchemas
2. Fix the caller so nested-namespace listing resolves the scope to the database level before calling
3. Inspect the scope object's type() before invoking and route unsupported cases to a different API
4. Add tests for namespace listing at each hierarchy level to catch scope-type mistakes early

Example fix

// before
client.listSchemas(SnowflakeIdentifier.ofSchema("db", "sc")); // throws
// after
client.listSchemas(SnowflakeIdentifier.ofDatabase("db")); // or SnowflakeIdentifier.ofRoot()

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

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

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

When it happens

Trigger: Calling listSchemas with a scope identifier whose type is neither ACCOUNT/ROOT nor DATABASE — e.g. passing a SCHEMA- or TABLE-typed SnowflakeIdentifier to SnowflakeCatalog.listNamespaces with an invalid hierarchy.

Common situations: Bug in caller code building SnowflakeIdentifier scopes, mixing up schema vs database identifiers when listing nested namespaces, or generic catalog adapters passing the wrong identifier level.

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 listIcebergTables
• 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/77b36612bf89de52. Report an issue: GitHub.

Appendix: source

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

    return databases;
  }

  @Override
  public List<SnowflakeIdentifier> listSchemas(SnowflakeIdentifier scope) {
    StringBuilder baseQuery = new StringBuilder("SHOW SCHEMAS");
    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;
      default:
        throw new IllegalArgumentException(
            String.format("Unsupported scope type for listSchemas: %s", scope));
    }

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

View on GitHub (pinned to 86d9c8fc54)