t8y2/dbx · error · IllegalArgumentException

MongoDB explain verbosity must be queryPlanner, executionSta

Error message

MongoDB explain verbosity must be queryPlanner, executionStats, or allPlansExecution

What it means

findExplainVerbosity validates the optional 'verbosity' parameter of the find explain command. It must be one of MongoDB's three explain modes: queryPlanner, executionStats, or allPlansExecution. Any other string throws this error; when omitted it defaults to queryPlanner.

Source

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

            find.append("collation", collation);
        }

        long skip = params.has("skip") ? params.get("skip").getAsLong() : 0;
        if (skip > 0) {
            find.append("skip", skip);
        }
        long limit = params.has("limit") ? params.get("limit").getAsLong() : 0;
        if (limit > 0) {
            find.append("limit", limit);
        }
        return new Document("explain", find)
            .append("verbosity", findExplainVerbosity(params));
    }

    private static String findExplainVerbosity(JsonObject params) {
        String verbosity = defaultString(stringOrNull(params, "verbosity"), "queryPlanner");
        if (!Set.of("queryPlanner", "executionStats", "allPlansExecution").contains(verbosity)) {
            throw new IllegalArgumentException(
                "MongoDB explain verbosity must be queryPlanner, executionStats, or allPlansExecution");
        }
        return verbosity;
    }

    private static Object findOne(JsonObject params) {
        MongoClient c = requireClient();
        String database = params.get("database").getAsString();
        String collection = params.get("collection").getAsString();
        Document filter = documentOrNull(params, "filter");
        Document projection = documentOrNull(params, "projection");
        Document options = documentOrNull(params, "options");
        Document sort = null;

        if (options != null) {
            for (String key : options.keySet()) {
                if (!"sort".equals(key)) {
                    throw new IllegalArgumentException("Unsupported findOne option: " + key);

View on GitHub (pinned to c0390bff16)

Solutions

1. Use exactly one of: queryPlanner, executionStats, allPlansExecution (lowercase)
2. Omit verbosity to get the default queryPlanner
3. Check spelling and case of the value
4. Map legacy verbosity names to the supported set before calling

Example fix

// before
{"collection":"users","filter":{},"verbosity":"allPlans"}
// after
{"collection":"users","filter":{},"verbosity":"allPlansExecution"}

const VERBOSITIES = new Set(['queryPlanner','executionStats','allPlansExecution']);
if (verbosity != null && !VERBOSITIES.has(verbosity)) throw new Error('bad verbosity: ' + verbosity);

function isExplainVerbosity(v) {
  return v == null || ['queryPlanner','executionStats','allPlansExecution'].includes(v);
}

try {
  result = agent.findExplain(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("MongoDB explain verbosity")) {
    params.verbosity = 'queryPlanner';
    result = agent.findExplain(params);
  } else throw e;
}

When it happens

Trigger: Calling the find-explain operation with verbosity set to a misspelled or unsupported value like "verbose", "allPlans", "QUERYPLANNER" (case-sensitive), or an empty string that is not null.

Common situations: Typos in verbosity values; assuming case-insensitivity; copying verbosity strings from other drivers or from the aggregate explain API which uses different wording; old config using deprecated modes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported peek startPosition: ${value}
• MongoDB aggregate option ${key} must be a non-negative integ
• Unsupported findOne option: ${key}
• Unsupported collation option: ${key}
• Invalid collation: locale must not be empty

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