t8y2/dbx · error · java.lang.IllegalArgumentException

MongoDB createUser user document contains reserved command f

Error message

MongoDB createUser user document contains reserved command fields

What it means

The agent assembles the createUser command itself, so the user_json document must not contain the command fields "createUser" or "writeConcern" — including them would either duplicate the command name or conflict with the write concern the agent attaches. buildCreateUserCommand rejects such documents with IllegalArgumentException.

Source

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

        );
        return Collections.singletonMap("name", name);
    }

    private static Object createUser(JsonObject params) {
        MongoClient client = requireClient();
        String database = params.get("database").getAsString();
        client.getDatabase(database).runCommand(buildCreateUserCommand(params));
        return Collections.singletonMap("affected_rows", 1);
    }

    static Document buildCreateUserCommand(JsonObject params) {
        Document user = requiredDocument(params, "user_json", "User document");
        Object username = user.remove("user");
        if (!(username instanceof String) || ((String) username).isBlank()) {
            throw new IllegalArgumentException("MongoDB createUser requires a non-empty user name");
        }
        if (user.containsKey("createUser") || user.containsKey("writeConcern")) {
            throw new IllegalArgumentException("MongoDB createUser user document contains reserved command fields");
        }

        Document command = new Document("createUser", username);
        command.putAll(user);
        Document writeConcern = documentOrNull(params, "write_concern_json");
        if (writeConcern != null) {
            command.put("writeConcern", writeConcern);
        }
        return command;
    }

    private static Document requiredDocument(JsonObject params, String key, String label) {
        Document document = documentOrNull(params, key);
        if (document == null) {
            throw new IllegalArgumentException(label + " are required");
        }
        return document;
    }

View on GitHub (pinned to c0390bff16)

Solutions

1. Remove the "createUser" field from user_json — the agent adds it from the "user" value.
2. Remove "writeConcern" from user_json and pass it via the write_concern_json parameter instead.
3. Keep user_json to user attributes only: pwd, roles, customData, mechanisms, etc.

Example fix

// before
{"user_json": {"createUser": "bob", "pwd": "x", "writeConcern": {"w": 1}}}
// after
{"user_json": {"user": "bob", "pwd": "x"}, "write_concern_json": {"w": 1}}

const reserved = ["createUser", "writeConcern"];
for (const k of reserved) {
  if (params.user_json && k in params.user_json) {
    throw new Error("Remove reserved field '" + k + "' from user_json");
  }
}

function hasNoReservedFields(userJson) {
  return userJson == null || (!("createUser" in userJson) && !("writeConcern" in userJson));
}

try {
  await agent.createUser({ database, user_json: doc });
} catch (e) {
  if (String(e.message).includes("reserved command fields")) {
    const { createUser, writeConcern, ...clean } = doc;
    await agent.createUser({ database, user_json: clean, write_concern_json: writeConcern });
  } else throw e;
}

When it happens

Trigger: Passing a full server-style command document as user_json, e.g. {"createUser": "bob", "pwd": "...", "roles": [...]}, or including a "writeConcern" key inside user_json.

Common situations: Copying a mongosh/db.createUser command document verbatim into user_json; migrating scripts that previously sent raw runCommand payloads; supplying writeConcern in the wrong place (it belongs in the top-level write_concern_json parameter).

Related errors

• MongoDB createUser requires a non-empty user name
• 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/c608f5bd7c017db0. Report an issue: GitHub.