github/copilot-sdk · error · IllegalArgumentException

Unknown ToolDefer value: + value

Error message

Unknown ToolDefer value: + value

What it means

Thrown by ToolDefer.fromValue when a string does not match any registered ToolDefer enum constant's value. The enum is looked up by its wire value; anything unrecognized is rejected with this IllegalArgumentException rather than silently defaulting.

Solutions

1. Use one of the enum's known values — check ToolDefer.values() / the constant definitions in ToolDefer.java
2. Reference ToolDefer.X.value instead of a raw string literal in calling code
3. Align client/server protocol versions so both sides know the same defer values
4. Handle unknown values gracefully at the boundary: try fromValue, fall back to a default mode for forward compatibility

Example fix

// before
ToolDefer mode = ToolDefer.fromValue("always"); // unknown
// after
ToolDefer mode = ToolDefer.fromValue("never"); // a registered value
// or: ToolDefer mode = Stream.of(ToolDefer.values()).filter(m -> m.value.equals(v)).findFirst().orElse(ToolDefer.NONE);

boolean known = Arrays.stream(ToolDefer.values()).anyMatch(m -> m.value.equals(value));

boolean isKnownToolDefer(String v) { return Arrays.stream(ToolDefer.values()).anyMatch(m -> m.value.equals(v)); }

ToolDefer mode; try { mode = ToolDefer.fromValue(v); } catch (IllegalArgumentException e) { mode = ToolDefer.NONE; /* log unknown value */ }

When it happens

Trigger: Calling ToolDefer.fromValue("...") with a typo, different casing, or a value from an older/newer protocol version not present in this library version.

Common situations: Client and SDK protocol version skew; config files carrying defer mode strings that predate a rename; hand-written constants instead of referencing the enum.

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 AgentMode value: + value
• Unknown AskUserVariant value: + value
• Unknown AutoTier value: + value
• Unknown MessageSource value: + value
• Unknown WorkspaceDiffFileChangeType value

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/ToolDefer.java:94

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

View on GitHub (pinned to cd8cf15dc3)