github/copilot-sdk · error · IllegalArgumentException

Unknown MessageSource value: + value

Error message

Unknown MessageSource value: + value

What it means

MessageSource.fromValue resolves a string to a MessageSource: it special-cases the SYSTEM value and accepts any "agent-"-prefixed string as a dynamic agent source. Any other value throws IllegalArgumentException. The library therefore only recognizes the system source and agent-prefixed sources.

Solutions

1. Check the exact SYSTEM constant spelling and the "agent-" prefix (lowercase, with hyphen) against your value.
2. Trim/normalize the input string before calling fromValue.
3. If you need a new source kind, upgrade the SDK or construct MessageSource via the supported public API instead of fromValue.
4. Catch IllegalArgumentException and map unknown sources to a default or reject them upstream with a clear validation error.

Example fix

// before
MessageSource src = MessageSource.fromValue(userInput); // "user" -> throws

// after
String v = userInput.trim().toLowerCase(Locale.ROOT);
MessageSource src = (v.startsWith("agent-") || v.equals("system"))
        ? MessageSource.fromValue(v)
        : MessageSource.SYSTEM;

static boolean isKnownMessageSource(String v) {
    String t = v == null ? "" : v.trim();
    return t.equals("system") || t.startsWith("agent-");
}

try {
    source = MessageSource.fromValue(value);
} catch (IllegalArgumentException e) {
    logger.warn("Unknown message source '" + value + "', using SYSTEM");
    source = MessageSource.SYSTEM;
}

When it happens

Trigger: Calling MessageSource.fromValue with a string that is neither exactly the SYSTEM value nor starts with "agent-" — e.g. "user", "tool", "Agent-1" (wrong case), or a trailing-space value.

Common situations: Routing messages with hand-written source strings; protocol changes introducing new source kinds not yet in the SDK; user input reaching message construction without normalization.

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
• 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/7c5ef320f32c788e. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/MessageSource.java:82

     * @return the matching source, or {@code null} if value is {@code null}
     * @throws IllegalArgumentException
     *             if the value does not match a known message source
     */
    @JsonCreator
    public static MessageSource fromValue(String value) {
        if (value == null) {
            return null;
        }
        if (USER.value.equals(value)) {
            return USER;
        }
        if (SYSTEM.value.equals(value)) {
            return SYSTEM;
        }
        if (value.startsWith("agent-")) {
            return new MessageSource(value);
        }
        throw new IllegalArgumentException("Unknown MessageSource value: " + value);
    }

    @Override
    public String toString() {
        return value;
    }

    @Override
    public boolean equals(Object other) {
        return other instanceof MessageSource source && value.equals(source.value);
    }

    @Override
    public int hashCode() {
        return value.hashCode();
    }
}

View on GitHub (pinned to cd8cf15dc3)