t8y2/dbx · error · RuntimeException

Connection failed

Error message

Connection failed

What it means

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.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/JsonRpcServer.java:166

        }
    }

    private Object dispatch(String method, JsonObject params) throws Exception {
        if (AgentProtocol.METHOD_HANDSHAKE.equals(method)) {
            return AgentProtocol.handshakeResult();
        }
        if (AgentProtocol.METHOD_CONNECT.equals(method)) {
            ConnectParams connectParams = gson.fromJson(params, ConnectParams.class);
            agent.connect(connectParams);
            lastConnectParams = connectParams;
            lastConnectionValidationTimeMillis = 0L;
            return Collections.singletonMap("ok", true);
        }
        if (AgentProtocol.METHOD_TEST_CONNECTION.equals(method)) {
            Map<String, Object> result = agent.testConnectionWithInfo(gson.fromJson(params, ConnectParams.class));
            if (!Boolean.TRUE.equals(result.get("ok"))) {
                Object error = result.get("error");
                throw new RuntimeException(error == null ? "Connection failed" : String.valueOf(error));
            }
            return result;
        }
        if (AgentProtocol.METHOD_VALIDATE_CONNECTION.equals(method)) {
            Connection conn = agent.getConnection();
            boolean valid = false;
            if (conn != null) {
                try {
                    valid = agent instanceof AbstractJdbcAgent jdbcAgent
                        ? jdbcAgent.isConnectionValid(conn, 2)
                        : !conn.isClosed() && conn.isValid(2);
                } catch (Exception | AbstractMethodError ignored) {
                }
            }
            if (!valid) {
                throw new IllegalStateException("Connection is not valid");
            }
            return Collections.singletonMap("ok", true);

View on GitHub (pinned to c0390bff16)

Solutions

1. Read the actual error message in the exception (it mirrors result.error) — fix the underlying connect problem it names
2. Verify host, port, database name, username and password in the connection params
3. Confirm the database is reachable from the agent host (network/firewall)
4. Confirm the required JDBC driver is on the agent's classpath

Example fix

// before
params = new ConnectParams("localhost", 9999, "db", "u", "p");
// after
params = new ConnectParams("db.internal", 5432, "db", "svc", "correct-password");
// then re-run test connection before calling other methods

// verify reachability before invoking test connection
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 3000); // host/port must accept TCP
}

boolean connectParamsOk(ConnectParams p) {
    return p != null && notBlank(p.host()) && p.port() > 0 && notBlank(p.user()) && p.password() != null;
}

When it happens

Trigger: 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.

Common situations: Wrong connection params entered in a client; database server down or firewalled; JDBC driver class missing on the agent classpath; expired credentials.

Related errors

• Connection is not valid
• H2 JDBC driver rejected URL: " + buildJdbcUrl(params)
• Informix connection failed.\nURL: " + url.replaceAll("//[^@]
• JDBC driver rejected connect for URL '" + url + "'
• JDBC pool registry must be attached before connecting

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/76ab7ead906474e8. Report an issue: GitHub.