github/copilot-sdk · error · IllegalArgumentException

defaultValue ' ' is not valid for type

Error message

defaultValue '<defaultValue>' is not valid for type <type simple name>

What it means

Param.validateDefaultValue() throws this when a default value string cannot be coerced/validated against the parameter's declared type. For enums it uses Enum.valueOf, so a name that is not an exact enum constant (wrong case, whitespace, or a value rather than a name) throws IllegalArgumentException with this message. The original RuntimeException is attached as the cause.

Solutions

1. Change defaultValue to exactly match the enum constant name (case-sensitive, no whitespace)
2. Print the allowed values with ClassName.values() / ClassName.<value>?.name and pick one
3. If the desired default is not a constant name, wrap the type with a custom coercion policy instead of relying on built-in validation

Example fix

// before
new Param("mode", Mode.class, "read");
// after
new Param("mode", Mode.class, "READ");

boolean ok = java.util.Arrays.stream(Mode.values()).anyMatch(e -> e.name().equals(defaultValue));
if (!ok) throw new IllegalArgumentException("default must be one of: " + java.util.Arrays.toString(Mode.values()));

boolean isValidEnumName(Class<? extends Enum<?>> t, String v) { return v != null && java.util.Arrays.stream(t.getEnumConstants()).anyMatch(e -> e.name().equals(v)); }

try { new Param("mode", Mode.class, candidate); } catch (IllegalArgumentException ex) { log.error("Bad default: {}", candidate, ex); }

When it happens

Trigger: Constructing a Param with a defaultValue where: the type is an enum and the string does not exactly match an enum constant name; or a RuntimeException occurs during built-in coercion of the default value for the type.

Common situations: Passing the enum's underlying value or label instead of its constant name; case mismatch (e.g. 'read' vs 'READ'); trailing whitespace from config files; locale/copy-paste typos in defaults declared in tool definitions.

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
• sessionFs.conventions must be either 'windows' or 'posix'

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/tool/Param.java:288

                return;
            }
            if (type == Byte.class || type == byte.class) {
                Byte.parseByte(defaultValue);
                return;
            }
            if (type == Boolean.class || type == boolean.class) {
                if (!"true".equalsIgnoreCase(defaultValue) && !"false".equalsIgnoreCase(defaultValue)) {
                    throw new IllegalArgumentException("must be 'true' or 'false'");
                }
                return;
            }
            if (type.isEnum()) {
                Class<? extends Enum> enumType = (Class<? extends Enum>) type;
                Enum.valueOf(enumType, defaultValue);
                return;
            }
        } catch (RuntimeException ex) {
            throw new IllegalArgumentException(
                    "defaultValue '" + defaultValue + "' is not valid for type " + type.getSimpleName(), ex);
        }

        throw new IllegalArgumentException(
                "defaultValue is not supported for type " + type.getName() + " without a custom coercion policy");
    }
}

View on GitHub (pinned to cd8cf15dc3)