t8y2/dbx · error · java.lang.IllegalArgumentException

Index keys are required

Error message

Index keys are required

What it means

createIndex builds a MongoDB createIndexes command whose index specification needs a "key" document mapping fields to sort directions. After the keys_json parameter passes the requiredDocument check (present), the agent additionally rejects an empty keys document. An index with no keys is meaningless, so it throws IllegalArgumentException.

Source

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

    }

    private static boolean serverRequiresSerialDropIndexes(MongoClient client, String database) {
        try {
            Document buildInfo = client.getDatabase(database).runCommand(new Document("buildInfo", 1));
            return serverVersionRequiresSerialDropIndexes(serverVersionFromBuildInfo(buildInfo));
        } catch (RuntimeException error) {
            // Without an explicit old version, preserve MongoDB's single-command array semantics.
            return false;
        }
    }

    private static Object createIndex(JsonObject params) {
        MongoClient c = requireClient();
        String database = params.get("database").getAsString();
        String collection = params.get("collection").getAsString();
        Document keys = requiredDocument(params, "keys_json", "Index keys");
        if (keys.isEmpty()) {
            throw new IllegalArgumentException("Index keys are required");
        }

        Document index = new Document("key", keys);
        Document options = documentOrNull(params, "options_json");
        if (options != null) {
            if (options.containsKey("key")) {
                throw new IllegalArgumentException("Index options cannot contain \"key\"; specify index fields in keys JSON");
            }
            index.putAll(options);
        }
        String name;
        if (!index.containsKey("name")) {
            name = defaultIndexName(keys);
            index.put("name", name);
        } else if (!(index.get("name") instanceof String)) {
            throw new IllegalArgumentException("Index option \"name\" must be a non-empty string");
        } else {
            name = (String) index.get("name");

View on GitHub (pinned to c0390bff16)

Solutions

1. Supply the index key fields, e.g. {"keys_json": {"field": 1}} or {"createdAt": -1}.
2. For compound indexes include every field, e.g. {"userId": 1, "createdAt": -1}.
3. If keys are computed at runtime, assert the resulting map is non-empty before calling createIndex.

Example fix

// before
{"database": "app", "collection": "orders", "keys_json": {}}
// after
{"database": "app", "collection": "orders", "keys_json": {"userId": 1, "createdAt": -1}}

if (!params.keys_json || Object.keys(params.keys_json).length === 0) {
  throw new Error("keys_json must contain at least one field, e.g. {field: 1}");
}

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

try {
  await agent.createIndex({ database, collection, keys_json: keys, options_json: opts });
} catch (e) {
  if (String(e.message).includes("Index keys are required")) {
    console.error("Supply keys_json like {field: 1}");
  } else throw e;
}

When it happens

Trigger: Calling createIndex with {"keys_json": {}} — the parameter is present but contains no fields.

Common situations: Templates or generated calls leaving keys_json empty; a serialization bug producing an empty map; copying an example and deleting the keys to fill in later.

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

• runCommand requires a non-empty command document
• Index options cannot contain "key"; specify index fields in
• Index option "name" must be a non-empty string
• MongoDB Legacy aggregate option hint must be an object
• MongoDB aggregate option ${key} must be a non-negative integ

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