github/copilot-sdk · error · IllegalArgumentException

Failed to coerce parameter ' + param.name() + ' to type +…

Error message

Failed to coerce parameter ' + param.name() + ' to type + type.getSimpleName()

What it means

Fallback thrown by ParamCoercion.coerce when the Jackson ObjectMapper cannot convert the raw value into the parameter's declared type via mapper.convertValue(raw, type). The original IllegalArgumentException from Jackson is wrapped as the cause. This is the catch-all for any parameter type not handled by the earlier specialized coercions.

Solutions

1. Read the cause (ex.getCause()) for Jackson's detailed mismatch report and align the argument with the declared type
2. Send arguments as the correct JSON shape matching the tool's parameter schema
3. Upgrade client and server so both sides use the same tool schema version
4. Catch IllegalArgumentException, wrap with context, and fail fast with the parameter name included

Example fix

// before
args.put("options", "a,b"); // String where List expected
// after
args.put("options", java.util.List.of("a", "b"));

try { mapper.convertValue(raw, declaredType); } catch (IllegalArgumentException e) { /* fix payload before invoking */ }

null

try { result = tool.invoke(args); } catch (IllegalArgumentException e) { Throwable cause = e.getCause(); /* inspect Jackson detail, log param name from message */ throw new ToolInvocationException(args, e); }

When it happens

Trigger: Invoking a tool with an argument whose shape does not fit the declared type — e.g. a Map where a POJO is expected, a String where a List is expected, or a value with incompatible fields for convertValue.

Common situations: Schema drift between client and server tool versions; nested JSON objects deserialized into generic Maps then passed as typed params; enum values or date strings Jackson cannot map.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Failed to serialize FFI JSON parameter.
• Unknown AgentMode value: + value
• Unknown AskUserVariant value: + value
• Unknown AutoTier value: + value
• Unknown MessageSource value: + value

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/ParamCoercion.java:106

                return (T) java.util.OptionalLong.of(((Number) raw).longValue());
            } catch (ClassCastException ex) {
                throw new IllegalArgumentException("Parameter '" + param.name()
                        + "' expected a numeric value for OptionalLong, got: " + raw.getClass().getSimpleName(), ex);
            }
        }
        if (type == java.util.OptionalDouble.class) {
            try {
                return (T) java.util.OptionalDouble.of(((Number) raw).doubleValue());
            } catch (ClassCastException ex) {
                throw new IllegalArgumentException("Parameter '" + param.name()
                        + "' expected a numeric value for OptionalDouble, got: " + raw.getClass().getSimpleName(), ex);
            }
        }

        try {
            return mapper.convertValue(raw, type);
        } catch (IllegalArgumentException ex) {
            throw new IllegalArgumentException(
                    "Failed to coerce parameter '" + param.name() + "' to type " + type.getSimpleName(), ex);
        }
    }

    /**
     * Parses a {@link Param}'s string default value into the declared Java type.
     *
     * <p>
     * Handles primitives, boxed types, {@link String}, {@link Boolean}, and enums
     * explicitly, mirroring the validation logic in {@link Param}. The
     * {@link ObjectMapper#readValue} fallback exists as a safety net but is not
     * expected to be reached in practice, since {@link Param} construction rejects
     * defaults for non-primitive/boxed/String/Boolean/enum types.
     *
     * @param <T>
     *            the target Java type
     * @param param
     *            the parameter descriptor carrying the default value

View on GitHub (pinned to cd8cf15dc3)