github/copilot-sdk · error · IllegalArgumentException

Unknown WorkspaceDiffMode value

Error message

Unknown WorkspaceDiffMode value: ${value}

What it means

WorkspaceDiffMode.fromValue is the Jackson @JsonCreator for the WorkspaceDiffMode enum. It throws IllegalArgumentException when the input string does not equal the value of any declared enum constant. The SDK cannot map the wire-format diff-mode string to a known enum constant.

Solutions

1. Update the Java SDK to the version matching the connected CLI so the enum contains the new mode.
2. Inspect the exception message for the unknown value and compare against the SDK's declared constants.
3. If you control the payload, send only values supported by your SDK version.

boolean known = Stream.of(WorkspaceDiffMode.values()).anyMatch(v -> v.getValue().equals(raw));
if (!known) log.warn("Unsupported diff mode: {}", raw);

try {
  WorkspaceDiffMode mode = WorkspaceDiffMode.fromValue(raw);
} catch (IllegalArgumentException e) {
  log.warn("Unknown diff mode '{}', using default", raw);
}

When it happens

Trigger: Deserializing a response/event containing a diffMode string not among the SDK's generated WorkspaceDiffMode constants, or calling fromValue directly with an unknown string.

Common situations: Version skew: the CLI emits a newly introduced diff mode while the Java SDK's generated enum predates it; typos when constructing values manually.

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

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

Appendix: source

Thrown at java/sdk/src/generated/java/com/github/copilot/generated/rpc/WorkspaceDiffMode.java:35

@javax.annotation.processing.Generated("copilot-sdk-codegen")
public enum WorkspaceDiffMode {
    /** The {@code unstaged} variant. */
    UNSTAGED("unstaged"),
    /** The {@code branch} variant. */
    BRANCH("branch"),
    /** The {@code session} variant. */
    SESSION("session");

    private final String value;
    WorkspaceDiffMode(String value) { this.value = value; }
    @com.fasterxml.jackson.annotation.JsonValue
    public String getValue() { return value; }
    @com.fasterxml.jackson.annotation.JsonCreator
    public static WorkspaceDiffMode fromValue(String value) {
        for (WorkspaceDiffMode v : values()) {
            if (v.value.equals(value)) return v;
        }
        throw new IllegalArgumentException("Unknown WorkspaceDiffMode value: " + value);
    }
}

View on GitHub (pinned to cd8cf15dc3)