{"record":{"id":"1ba6a5225b4ee113","repo":"t8y2/dbx","slug":"runcommand-requires-a-non-empty-command-document","errorCode":null,"errorMessage":"runCommand requires a non-empty command document","messagePattern":"runCommand requires a non-empty command document","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":948,"sourceCode":"        if (n instanceof Number number) {\n            return number.longValue();\n        }\n        return 0L;\n    }\n\n    private static Object serverVersion(JsonObject params) {\n        MongoClient c = requireClient();\n        String database = defaultString(stringOrNull(params, \"database\"), \"admin\");\n        Document buildInfo = c.getDatabase(database).runCommand(new Document(\"buildInfo\", 1));\n        return serverVersionFromBuildInfo(buildInfo);\n    }\n\n    private static Object runCommand(JsonObject params) {\n        MongoClient c = requireClient();\n        String database = params.get(\"database\").getAsString();\n        Document command = documentOrNull(params, \"command_json\");\n        if (command == null || command.isEmpty()) {\n            throw new IllegalArgumentException(\"runCommand requires a non-empty command document\");\n        }\n        Document response = c.getDatabase(database).runCommand(command);\n        List<Map<String, Object>> documents = new ArrayList<>();\n        documents.add(bsonToJson(response));\n        List<JsonObject> extendedDocuments = new ArrayList<>();\n        extendedDocuments.add(bsonToExtendedJson(response));\n        return documentQueryResultWithExtended(documents, extendedDocuments, 1);\n    }\n\n    static String serverVersionFromBuildInfo(Document buildInfo) {\n        String version = buildInfo.getString(\"version\");\n        if (version == null || version.isBlank()) {\n            throw new IllegalStateException(\"MongoDB server version not found\");\n        }\n        return version;\n    }\n\n    static boolean serverVersionRequiresSerialDropIndexes(String version) {","sourceCodeStart":930,"sourceCodeEnd":966,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L930-L966","documentation":"runCommand forwards a raw command document to the MongoDB server via MongoClient.runCommand. An empty or missing command document cannot be sent, so the agent validates up front and throws IllegalArgumentException. This prevents a useless round-trip and gives a clearer error than the server would.","triggerScenarios":"Calling the runCommand tool without the command_json parameter, with null, or with an empty object {\"command_json\": {}}.","commonSituations":"LLM/tool callers omitting the command_json argument; scripts that build the command document conditionally and end up with an empty map; renaming the parameter key so the lookup returns null.","solutions":["Provide a non-empty command document in the command_json parameter, e.g. {\"buildInfo\": 1}.","Verify the parameter name is exactly command_json in your tool invocation.","If the command is built dynamically, check it is non-empty before calling runCommand."],"exampleFix":"// before\n{\"database\": \"admin\", \"command_json\": {}}\n// after\n{\"database\": \"admin\", \"command_json\": {\"buildInfo\": 1}}","handlingStrategy":"validation","validationCode":"if (!params.command_json || Object.keys(params.command_json).length === 0) {\n  throw new Error(\"command_json must be a non-empty object, e.g. {\\\"buildInfo\\\": 1}\");\n}","typeGuard":"function isNonEmptyCommand(cmd) {\n  return cmd != null && typeof cmd === \"object\" && Object.keys(cmd).length > 0;\n}","tryCatchPattern":"try {\n  const res = await agent.runCommand({ database: \"admin\", command_json: cmd });\n} catch (e) {\n  if (String(e.message).includes(\"runCommand requires a non-empty\")) {\n    console.error(\"command_json missing or empty; supply e.g. {buildInfo: 1}\");\n  } else throw e;\n}","preventionTips":["Always send a concrete command such as {\"buildInfo\": 1} or {\"ping\": 1}.","Check parameter naming: it is command_json, not command.","Guard dynamically built command maps with an isEmpty check before calling."],"tags":["mongodb","validation","empty-input","runcommand"],"backgroundTag":"missing-required-parameter","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"}