apache/iceberg · warning · UncheckedSQLException

Failed to close connection

Error message

Failed to close connection

What it means

Thrown when closing a pooled JDBC connection raises a SQLException. JdbcClientPool.close() calls client.close() and converts failures into UncheckedSQLException. This usually signals an already-broken connection or driver-level teardown problem while releasing resources back to the pool.

Solutions

1. Set connection validation and idle timeout settings so stale connections are evicted before reuse/close.
2. Check for a keepalive/test-on-borrow configuration supported by JdbcClientPool properties (e.g. keepalive.time).
3. Verify network stability between client and database.
4. Upgrade the JDBC driver if close() failures are a known driver issue.
5. Catch UncheckedSQLException around catalog close in application shutdown code to avoid masking other shutdown errors.

Example fix

// before
Map<String, String> props = Map.of("uri", url); // no keepalive, stale conns
// after
Map<String, String> props = Map.of(
  "uri", url,
  "keepalive.time", "120000",
  "jdbc.test-on-borrow", "true");

try {
  catalog.close();
} catch (UncheckedSQLException e) {
  org.slf4j.LoggerFactory.getLogger("app").warn("Connection close failed; pool may hold stale connections", e);
}

When it happens

Trigger: JdbcClientPool.close(client) fails when Connection.close() throws SQLException — e.g. the connection was already terminated by the server or network dropped mid-close.

Common situations: Database restarted or connection killed by idle timeouts while in the pool, network partition during teardown, driver bugs on close after a stale connection.

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

• Cannot check and eventually update SQL schema
• Cannot initialize JDBC catalog
• Cannot initialize JDBC table maintenance lock
• Cannot initialize JDBC table maintenance lock
• Cannot initialize JDBC table maintenance lock

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcClientPool.java:105

      Properties dbProps = JdbcUtil.filterAndRemovePrefix(properties, JdbcCatalog.PROPERTY_PREFIX);
      return DriverManager.getConnection(dbUrl, dbProps);
    } catch (SQLException e) {
      throw new UncheckedSQLException(e, "Failed to connect: %s", dbUrl);
    }
  }

  @Override
  protected Connection reconnect(Connection client) {
    close(client);
    return newClient();
  }

  @Override
  protected void close(Connection client) {
    try {
      client.close();
    } catch (SQLException e) {
      throw new UncheckedSQLException(e, "Failed to close connection");
    }
  }

  @Override
  protected boolean isConnectionException(Exception e) {
    return super.isConnectionException(e)
        || (e instanceof SQLException
            && retryableStatusCodes.contains(((SQLException) e).getSQLState()));
  }
}

View on GitHub (pinned to 86d9c8fc54)