t8y2/dbx · error · java.lang.IllegalArgumentException

MongoDB createUser requires a non-empty user name

Error message

MongoDB createUser requires a non-empty user name

What it means

buildCreateUserCommand constructs a createUser command from a user_json document. The "user" field inside that document is mandatory and must be a non-blank string, because it becomes the command's createUser value. If it's missing, not a string, or blank, the agent throws IllegalArgumentException before talking to the server.

Source

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

        c.getDatabase(database).runCommand(
            new Document("createIndexes", collection)
                .append("indexes", Collections.singletonList(index))
        );
        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");

View on GitHub (pinned to c0390bff16)

Solutions

1. Add a non-empty "user" field to user_json, e.g. {"user": "appUser", "pwd": "...", "roles": ["readWrite"]}.
2. Ensure the value is a string, not a number or object.
3. Trim the username input and reject blank values before building the document.

Example fix

// before
{"database": "admin", "user_json": {"pwd": "s3cret", "roles": ["readWrite"]}}
// after
{"database": "admin", "user_json": {"user": "appUser", "pwd": "s3cret", "roles": ["readWrite"]}}

const u = params.user_json || {};
if (typeof u.user !== "string" || u.user.trim() === "") {
  throw new Error("user_json.user must be a non-empty string");
}

function hasValidUsername(userJson) {
  return userJson != null && typeof userJson.user === "string" && userJson.user.trim() !== "";
}

try {
  await agent.createUser({ database, user_json: doc });
} catch (e) {
  if (String(e.message).includes("requires a non-empty user name")) {
    console.error("Add a non-empty 'user' field to user_json");
  } else throw e;
}

When it happens

Trigger: Calling createUser with user_json missing the "user" field, e.g. {"pwd": "s3cret", "roles": []}, or with {"user": ""} / a non-string user value.

Common situations: Templates omitting the username; form/config submissions with an empty username; forgetting that the agent requires the name inside user_json rather than as a top-level parameter.

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

• Invalid collation: locale must not be empty
• MongoDB createUser user document contains reserved command f
• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta
• Unsupported findOne option: ${key}

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