t8y2/dbx · error · java.lang.IllegalArgumentException

Unknown method: <method>

Error message

Unknown method: <method>

What it means

The agent's request dispatch switch has a `default` branch that throws IllegalArgumentException("Unknown method: ...") when the incoming `method` string matches none of the supported protocol methods. This guards the agent protocol boundary: any typo'd, unsupported, or version-mismatched method name is rejected explicitly.

Source

Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:1871

            case AgentProtocol.MONGO_METHOD_DROP_INDEXES -> dropIndexes(params);
            case AgentProtocol.MONGO_METHOD_DROP_COLLECTION -> dropCollection(params);
            case AgentProtocol.MONGO_METHOD_CLONE_COLLECTION -> cloneCollection(params);
            case AgentProtocol.MONGO_METHOD_DROP_DATABASE -> dropDatabase(params);
            case AgentProtocol.MONGO_METHOD_INSERT_DOCUMENT -> insertDocument(params);
            case AgentProtocol.MONGO_METHOD_INSERT_DOCUMENTS -> insertDocuments(params);
            case AgentProtocol.MONGO_METHOD_UPDATE_DOCUMENT -> updateDocument(params);
            case AgentProtocol.MONGO_METHOD_UPDATE_DOCUMENTS -> updateDocuments(params);
            case AgentProtocol.MONGO_METHOD_DELETE_DOCUMENT -> deleteDocument(params);
            case AgentProtocol.MONGO_METHOD_DELETE_DOCUMENTS -> deleteDocuments(params);
            case AgentProtocol.MONGO_METHOD_RUN_COMMAND -> runCommand(params);
            case AgentProtocol.METHOD_DISCONNECT, AgentProtocol.METHOD_SHUTDOWN -> {
                closeLegacyClient();
                if (AgentProtocol.METHOD_SHUTDOWN.equals(method)) {
                    System.exit(0);
                }
                yield Collections.singletonMap("ok", true);
            }
            default -> throw new IllegalArgumentException("Unknown method: " + method);
        };
    }

    static AgentProtocol.HandshakeResult runtimeHandshakeResult() {
        return AgentProtocol.mongoLegacyMultiSessionHandshakeResult();
    }

    private static MongoClient requireClient() {
        MongoClient client = CURRENT_CLIENT.get();
        if (client == null) {
            client = legacyClient;
        }
        if (client == null) {
            throw new IllegalStateException("Not connected");
        }
        return client;
    }

View on GitHub (pinned to c0390bff16)

Solutions

  1. Check the exact method name against the AgentProtocol constants supported by this agent version.
  2. Fix casing/typo/whitespace in the method string (names are matched exactly).
  3. Upgrade the agent binary if the method exists only in a newer protocol version.
  4. Add debug logging of the raw `method` value to spot invisible whitespace or encoding issues.

Example fix

// before
{"method": "mongo.updateMany"}
// after (exact protocol method name)
{"method": "updateMany"}
Defensive patterns

Strategy: try-catch

Validate before calling

// Java: check method against a known whitelist before dispatch
Set<String> supported = Set.of("connect", "find", "insert", "updateOne", "updateMany", "delete", "shutdown");
if (!supported.contains(method)) {
    throw new IllegalArgumentException("Unsupported method: " + method);
}

Try / catch

try { response = agent.dispatch(request); }
catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown method:")) {
    log.error("Method {} not supported by agent version {}", request.method, agentVersion);
    // surface a client-side 'upgrade agent' error
  } else throw e;
}

Prevention

When it happens

Trigger: Sending a request frame with `method` set to something like `mongo.query` or `listDatabases ` (trailing space) that is not in the AgentProtocol switch; using a newer client against an older agent build lacking that method.

Common situations: Typos in method names; case mismatches (e.g. `ping` vs `PING`); client/agent version skew where the client uses a method the agent doesn't implement; custom scripts calling internal methods.

Related errors

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