github/copilot-sdk · error · IllegalArgumentException

Unknown AgentMode value: + value

Error message

Unknown AgentMode value: + value

What it means

AgentMode.fromValue maps a protocol string (e.g. "ask", "agent", "edit") to its AgentMode enum constant. If no constant's value equals the input, it throws IllegalArgumentException with the offending value. This guards against unknown or mistyped agent mode strings arriving from config or RPC payloads.

Solutions

1. Log the exact value and compare against AgentMode.values() to see the accepted set.
2. Fix the typo/case to match one of the enum's documented values.
3. Upgrade the SDK to a version that supports the new AgentMode value.
4. If the value is user input, validate it against the enum's allowed values before calling fromValue, or catch IllegalArgumentException and fall back to a default mode.

Example fix

// before
AgentMode mode = AgentMode.fromValue(config.getString("mode"));

// after
String v = config.getString("mode", "ask");
AgentMode mode;
try {
    mode = AgentMode.fromValue(v);
} catch (IllegalArgumentException e) {
    logger.warn("Unknown agent mode '" + v + "', defaulting to ask");
    mode = AgentMode.ASK;
}

static boolean isKnownAgentMode(String v) {
    for (AgentMode m : AgentMode.values()) {
        if (m.name().equalsIgnoreCase(v)) return true;
    }
    return false;
}

try {
    mode = AgentMode.fromValue(value);
} catch (IllegalArgumentException e) {
    logger.warn("Unknown AgentMode '" + value + "'");
    mode = AgentMode.ASK; // documented default
}

When it happens

Trigger: Calling AgentMode.fromValue with a string that matches no enum constant — typos, wrong casing ("Agent" vs "agent"), or a mode introduced in a newer protocol version than the SDK supports.

Common situations: User-supplied agent mode from config/CLI passed straight through; a server emitting a new mode value after a protocol update; older SDK version receiving newer payloads.

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

• Unknown AskUserVariant value: + value
• Unknown AutoTier value: + value
• Unknown MessageSource value: + value
• Required parameter ' + param.name() + ' is missing from…
• Unknown ToolDefer value: + value

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/d21ec07420da5eeb. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/AgentMode.java:70

     *
     * @param value
     *            the JSON string value
     * @return the matching {@code AgentMode}, or {@code null} if value is
     *         {@code null}
     * @throws IllegalArgumentException
     *             if the value does not match any known agent mode
     */
    @JsonCreator
    public static AgentMode fromValue(String value) {
        if (value == null) {
            return null;
        }
        for (AgentMode mode : values()) {
            if (mode.value.equals(value)) {
                return mode;
            }
        }
        throw new IllegalArgumentException("Unknown AgentMode value: " + value);
    }
}

View on GitHub (pinned to cd8cf15dc3)