{"record":{"id":"76ab7ead906474e8","repo":"t8y2/dbx","slug":"connection-failed","errorCode":null,"errorMessage":"Connection failed","messagePattern":"Connection failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java","lineNumber":166,"sourceCode":"        }\n    }\n\n    private Object dispatch(String method, JsonObject params) throws Exception {\n        if (AgentProtocol.METHOD_HANDSHAKE.equals(method)) {\n            return AgentProtocol.handshakeResult();\n        }\n        if (AgentProtocol.METHOD_CONNECT.equals(method)) {\n            ConnectParams connectParams = gson.fromJson(params, ConnectParams.class);\n            agent.connect(connectParams);\n            lastConnectParams = connectParams;\n            lastConnectionValidationTimeMillis = 0L;\n            return Collections.singletonMap(\"ok\", true);\n        }\n        if (AgentProtocol.METHOD_TEST_CONNECTION.equals(method)) {\n            Map<String, Object> result = agent.testConnectionWithInfo(gson.fromJson(params, ConnectParams.class));\n            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);","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java#L148-L184","documentation":"JsonRpcServer.dispatch wraps test-connection results: if agent.testConnectionWithInfo returns a map without ok=true, dispatch throws RuntimeException with the stored error (or the generic 'Connection failed'). It converts a structured failure result into a JSON-RPC error for the caller.","triggerScenarios":"Calling the test-connection JSON-RPC method with unreachable host/port, bad credentials, unsupported driver, or timeout — any case where the agent's result map contains ok=false or omits ok.","commonSituations":"Wrong connection params entered in a client; database server down or firewalled; JDBC driver class missing on the agent classpath; expired credentials.","solutions":["Read the actual error message in the exception (it mirrors result.error) — fix the underlying connect problem it names","Verify host, port, database name, username and password in the connection params","Confirm the database is reachable from the agent host (network/firewall)","Confirm the required JDBC driver is on the agent's classpath"],"exampleFix":"// before\nparams = new ConnectParams(\"localhost\", 9999, \"db\", \"u\", \"p\");\n// after\nparams = new ConnectParams(\"db.internal\", 5432, \"db\", \"svc\", \"correct-password\");\n// then re-run test connection before calling other methods","handlingStrategy":"validation","validationCode":"// verify reachability before invoking test connection\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(host, port), 3000); // host/port must accept TCP\n}","typeGuard":"boolean connectParamsOk(ConnectParams p) {\n    return p != null && notBlank(p.host()) && p.port() > 0 && notBlank(p.user()) && p.password() != null;\n}","tryCatchPattern":null,"preventionTips":["Validate connection parameters before sending test connection","Keep the JDBC driver on the agent classpath and verify at startup","Test network/firewall reachability to the database from the agent host","Surface result.error details in client UI instead of the generic message"],"tags":["jsonrpc","connection","jdbc","connectivity"],"backgroundTag":"connection-failed","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"}