t8y2/dbx · error · java.lang.IllegalArgumentException

Index option "name" must be a non-empty string

Error message

Index option "name" must be a non-empty string

What it means

When the index spec's "name" option is present but is not a String (e.g. a number), createIndex throws IllegalArgumentException because MongoDB index names must be strings. The message says "non-empty string" though this specific throw only covers the wrong-type case; the blank check is handled separately.

Source

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

        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");
            if (name.isBlank()) {
                throw new IllegalArgumentException("Index option \"name\" must be a non-empty string");
            }
        }

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

View on GitHub (pinned to c0390bff16)

Solutions

  1. Change the "name" option to a string, e.g. {"name": "userId_1"}.
  2. Omit the name entirely and let the agent derive the default name from the keys.
  3. Add a type check on the name in whatever code builds the options document.

Example fix

// before
{"keys_json": {"email": 1}, "options_json": {"name": 42}}
// after
{"keys_json": {"email": 1}, "options_json": {"name": "email_1"}}
Defensive patterns

Strategy: validation

Validate before calling

if (params.options_json && "name" in params.options_json && typeof params.options_json.name !== "string") {
  params.options_json.name = String(params.options_json.name);
}

Type guard

function hasStringIndexName(options) {
  return options == null || !("name" in options) || typeof options.name === "string";
}

Try / catch

try {
  await agent.createIndex({ database, collection, keys_json: keys, options_json: options });
} catch (e) {
  if (String(e.message).includes('"name" must be a non-empty string')) {
    // coerce name to string or drop it and retry with the default name
  } else throw e;
}

Prevention

When it happens

Trigger: Calling createIndex with options_json like {"name": 42} or {"name": true}, or any non-string name value.

Common situations: Programmatic index builders that store the name as an integer; JSON schemas without type checks; templating errors substituting a numeric id as the index name.

Related errors

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