{"record":{"id":"f15e636f445bcd64","repo":"t8y2/dbx","slug":"connection-is-not-valid","errorCode":null,"errorMessage":"Connection is not valid","messagePattern":"Connection is not valid","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java","lineNumber":182,"sourceCode":"            if (!Boolean.TRUE.equals(result.get(\"ok\"))) {\n                Object error = result.get(\"error\");\n                throw new RuntimeException(error == null ? \"Connection failed\" : String.valueOf(error));\n            }\n            return result;\n        }\n        if (AgentProtocol.METHOD_VALIDATE_CONNECTION.equals(method)) {\n            Connection conn = agent.getConnection();\n            boolean valid = false;\n            if (conn != null) {\n                try {\n                    valid = agent instanceof AbstractJdbcAgent jdbcAgent\n                        ? jdbcAgent.isConnectionValid(conn, 2)\n                        : !conn.isClosed() && conn.isValid(2);\n                } catch (Exception | AbstractMethodError ignored) {\n                }\n            }\n            if (!valid) {\n                throw new IllegalStateException(\"Connection is not valid\");\n            }\n            return Collections.singletonMap(\"ok\", true);\n        }\n        ensureLiveConnection(method);\n        if (AgentProtocol.METHOD_CONNECTION_INFO.equals(method)) {\n            Map<String, Object> result = new LinkedHashMap<>();\n            result.put(\"identifierQuote\", agent.getIdentifierQuote());\n            Map<String, String> databaseInfo = agent.getDatabaseInfo();\n            if (databaseInfo != null && !databaseInfo.isEmpty()) {\n                result.put(\"databaseInfo\", databaseInfo);\n            }\n            return result;\n        }\n        if (AgentProtocol.METHOD_LIST_DATABASES.equals(method)) {\n            return agent.listDatabases();\n        }\n        if (AgentProtocol.METHOD_LIST_SCHEMAS.equals(method)) {\n            switchCatalog(params);","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java#L164-L200","documentation":"The validate-connection JSON-RPC method throws IllegalStateException('Connection is not valid') when, after acquiring the agent's connection, conn.isValid(2) (or the JDBC agent's validity check) reports the connection unusable. isValid calls are wrapped so any exception or AbstractMethodError simply leaves valid=false, triggering this error.","triggerScenarios":"Calling METHOD_VALIDATE_CONNECTION while the connection is closed, dropped by the server, timed out, or while no connection has ever been established; also when a driver throws from isValid (older drivers may not implement it).","commonSituations":"Database restarted or idle-connection killed between calls; network interruption; driver lacking isValid support; calling validate before connect.","solutions":["Call connect first (or reconnect) to establish a fresh connection, then validate","Enable a connection pool/keepalive or validation query to avoid stale connections","Upgrade the JDBC driver if isValid throws or is unsupported (AbstractMethodError path)","Handle the error client-side by reconnecting and retrying validation"],"exampleFix":"// before\nboolean ok = rpc.call(\"validateConnection\");\n// after\nboolean ok;\ntry {\n    ok = rpc.call(\"validateConnection\");\n} catch (IllegalStateException e) {\n    rpc.call(\"connect\", connectParams);\n    ok = rpc.call(\"validateConnection\");\n}","handlingStrategy":"retry","validationCode":"// ensure a connection exists before validating\nMap<String,Object> ok = rpc.call(\"testConnection\", connectParams); // must return ok=true first","typeGuard":"boolean sessionConnected(Map<String,Object> state) { return Boolean.TRUE.equals(state.get(\"ok\")) && Boolean.TRUE.equals(state.get(\"connected\")); }","tryCatchPattern":"boolean validateWithRetry() {\n    for (int i = 0; i < 2; i++) {\n        try { return rpc.call(\"validateConnection\"); }\n        catch (IllegalStateException e) { rpc.call(\"connect\", connectParams); }\n    }\n    return false;\n}","preventionTips":["Always connect before validating","Enable keepalive/timeout settings to reduce dropped connections","Upgrade drivers that throw on isValid()","Reconnect automatically on validation failure"],"tags":["jsonrpc","jdbc","connection-validity","stale-connection"],"backgroundTag":"connection-not-valid","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}