t8y2/dbx · error · java.lang.IllegalArgumentException

runCommand requires a non-empty command document

Error message

runCommand requires a non-empty command document

What it means

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.

Source

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

        if (n instanceof Number number) {
            return number.longValue();
        }
        return 0L;
    }

    private static Object serverVersion(JsonObject params) {
        MongoClient c = requireClient();
        String database = defaultString(stringOrNull(params, "database"), "admin");
        Document buildInfo = c.getDatabase(database).runCommand(new Document("buildInfo", 1));
        return serverVersionFromBuildInfo(buildInfo);
    }

    private static Object runCommand(JsonObject params) {
        MongoClient c = requireClient();
        String database = params.get("database").getAsString();
        Document command = documentOrNull(params, "command_json");
        if (command == null || command.isEmpty()) {
            throw new IllegalArgumentException("runCommand requires a non-empty command document");
        }
        Document response = c.getDatabase(database).runCommand(command);
        List<Map<String, Object>> documents = new ArrayList<>();
        documents.add(bsonToJson(response));
        List<JsonObject> extendedDocuments = new ArrayList<>();
        extendedDocuments.add(bsonToExtendedJson(response));
        return documentQueryResultWithExtended(documents, extendedDocuments, 1);
    }

    static String serverVersionFromBuildInfo(Document buildInfo) {
        String version = buildInfo.getString("version");
        if (version == null || version.isBlank()) {
            throw new IllegalStateException("MongoDB server version not found");
        }
        return version;
    }

    static boolean serverVersionRequiresSerialDropIndexes(String version) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Provide a non-empty command document in the command_json parameter, e.g. {"buildInfo": 1}.
2. Verify the parameter name is exactly command_json in your tool invocation.
3. If the command is built dynamically, check it is non-empty before calling runCommand.

Example fix

// before
{"database": "admin", "command_json": {}}
// after
{"database": "admin", "command_json": {"buildInfo": 1}}

if (!params.command_json || Object.keys(params.command_json).length === 0) {
  throw new Error("command_json must be a non-empty object, e.g. {\"buildInfo\": 1}");
}

function isNonEmptyCommand(cmd) {
  return cmd != null && typeof cmd === "object" && Object.keys(cmd).length > 0;
}

try {
  const res = await agent.runCommand({ database: "admin", command_json: cmd });
} catch (e) {
  if (String(e.message).includes("runCommand requires a non-empty")) {
    console.error("command_json missing or empty; supply e.g. {buildInfo: 1}");
  } else throw e;
}

When it happens

Trigger: Calling the runCommand tool without the command_json parameter, with null, or with an empty object {"command_json": {}}.

Common situations: 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.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Index keys are required
• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta
• Unsupported findOne option: ${key}
• Unsupported collation option: ${key}

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