apache/iceberg · error · RuntimeException

Failed to list schemas for scope '%s'

Error message

Failed to list schemas for scope '%s'

What it means

JdbcSnowflakeClient.listSchemas runs 'SHOW SCHEMAS ... IN DATABASE IDENTIFIER(?)' and wraps any SQLException into an IcebergException 'Failed to list schemas for scope %s'. It indicates the SHOW SCHEMAS query failed - typically the database does not exist or is inaccessible, or the connection/privileges are insufficient. If the database is not found, snowflakeExceptionToIcebergException maps it to NoSuchNamespaceException instead (only when the scope identifier is DATABASE type).

Source

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

        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);
    }
    schemas.forEach(
        schema ->
            Preconditions.checkState(
                schema.type() == SnowflakeIdentifier.Type.SCHEMA,
                "Expected SCHEMA, got identifier '%s' for scope '%s'",
                schema,
                scope));
    return schemas;
  }

  @Override
  public List<SnowflakeIdentifier> listIcebergTables(SnowflakeIdentifier scope) {
    StringBuilder baseQuery = new StringBuilder("SHOW ICEBERG TABLES");

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the database exists and the name matches exactly (casing/quoted identifiers): run SHOW DATABASES and compare
2. Check the configured role has USAGE privileges on the database, or switch roles
3. Catch NoSuchNamespaceException specifically when the scope may not exist (it is mapped for DATABASE scopes with known error codes)
4. Inspect the underlying SQLException cause for auth/network issues and retry transient errors

Example fix

// before
catalog.listNamespaces(Namespace.of("MYDB")); // SQLException -> 'Failed to list schemas for scope'
// after
try {
  catalog.listNamespaces(Namespace.of("MYDB"));
} catch (NoSuchNamespaceException e) {
  // handle missing database
} catch (IcebergException e) {
  // inspect cause: privileges, auth, or connectivity
}

// check the database exists before listing its schemas
boolean exists = catalog.listNamespaces().stream()
    .anyMatch(ns -> ns.level(0).equalsIgnoreCase(dbName));
if (!exists) {
  throw new NoSuchNamespaceException(ns); // handle before querying
}

try {
  catalog.listNamespaces(Namespace.of(dbName));
} catch (NoSuchNamespaceException e) {
  // expected missing-scope path
} catch (IcebergException e) {
  SQLException cause = findCause(e, SQLException.class);
  // distinguish privilege/auth (error code) vs transient; retry transient only
}

When it happens

Trigger: Calling listSchemas(scope) (e.g., SnowflakeCatalog.listNamespaces(database)) where the JDBC query raises SQLException: nonexistent database name, no privileges on the database, dropped database, broken connection, or bad identifier format passed to IDENTIFIER(?).

Common situations: Typos or wrong casing in database names (Snowflake names are case-sensitive unquoted); database dropped between listing and use; role lacks USAGE on the database; expired auth; transient network failures.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed to check if database '%s' exists
• Failed to check if schema '%s' exists
• Interrupted while getting table metadata for '%s'
• Failed to load expected JDBC SnowflakeDriver - if queries fa
• Failed to list databases

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