t8y2/dbx · error · java.lang.IllegalArgumentException

<label> are required

Error message

<label> are required

What it means

requiredDocument is a generic helper: it fetches a JSON document parameter and throws IllegalArgumentException("<label> are required") when the parameter is absent or null. The message template uses the caller-supplied label, e.g. "Index keys are required" or "User document are required". It signals a missing required document-typed parameter for the tool being invoked.

Source

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

            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;
    }

    static String defaultIndexName(Document keys) {
        List<String> parts = new ArrayList<>();
        for (Map.Entry<String, Object> entry : keys.entrySet()) {
            parts.add(entry.getKey() + "_" + defaultIndexNameValue(entry.getValue()));
        }
        return String.join("_", parts);
    }

    private static String defaultIndexNameValue(Object value) {
        if (value instanceof Double number && Double.isFinite(number)) {
            // The Rust driver's BSON formatter omits a fractional suffix for
            // whole doubles (for example, 1.0 becomes 1). Keep unnamed index
            // names identical on Native and Legacy connections.
            return BigDecimal.valueOf(number).stripTrailingZeros().toPlainString();

View on GitHub (pinned to c0390bff16)

Solutions

1. Add the missing parameter named in your call (per the tool's schema), e.g. keys_json for createIndex or user_json for createUser.
2. Check spelling of the parameter key — requiredDocument returns null for any unknown key.
3. Ensure your request builder always populates the document before invoking the tool, e.g. Objects.requireNonNull(map, "keys_json").

Example fix

// before
{"database": "app", "collection": "users"}  // createIndex, no keys_json
// after
{"database": "app", "collection": "users", "keys_json": {"email": 1}}

function requireDoc(params, key) {
  if (params == null || params[key] == null) {
    throw new Error(key + " is required (must be a non-null JSON object)");
  }
  return params[key];
}
// usage: requireDoc(params, "keys_json"); requireDoc(params, "user_json");

function isPresentDocument(params, key) {
  return params != null && params[key] != null && typeof params[key] === "object";
}

try {
  await agent.toolCall(params);
} catch (e) {
  if (/are required$/.test(String(e.message))) {
    const key = String(e.message).split(" ")[0]; // e.g. "Index", "User"
    console.error("Missing required document parameter for " + key + "; check the tool schema for the exact key name");
  } else throw e;
}

When it happens

Trigger: Calling any tool that needs a document parameter (e.g. createIndex without keys_json, createUser without user_json) while that key is missing or explicitly null in params.

Common situations: LLM/tool invocations omitting an argument; typos in the parameter name (keys vs keys_json); serialization dropping null/empty fields; building requests dynamically where the document is only set conditionally.

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

• agentSessionId is 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/a04e89a9a3e88239. Report an issue: GitHub.