{"record":{"id":"9bd8f4c5948435db","repo":"github/copilot-sdk","slug":"failed-to-coerce-parameter-param-name-to","errorCode":null,"errorMessage":"Failed to coerce parameter ' + param.name() + ' to type + type.getSimpleName()","messagePattern":"Failed to coerce parameter ' \\+ param\\.name\\(\\) \\+ ' to type \\+ type\\.getSimpleName\\(\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/rpc/ParamCoercion.java","lineNumber":106,"sourceCode":"                return (T) java.util.OptionalLong.of(((Number) raw).longValue());\n            } catch (ClassCastException ex) {\n                throw new IllegalArgumentException(\"Parameter '\" + param.name()\n                        + \"' expected a numeric value for OptionalLong, got: \" + raw.getClass().getSimpleName(), ex);\n            }\n        }\n        if (type == java.util.OptionalDouble.class) {\n            try {\n                return (T) java.util.OptionalDouble.of(((Number) raw).doubleValue());\n            } catch (ClassCastException ex) {\n                throw new IllegalArgumentException(\"Parameter '\" + param.name()\n                        + \"' expected a numeric value for OptionalDouble, got: \" + raw.getClass().getSimpleName(), ex);\n            }\n        }\n\n        try {\n            return mapper.convertValue(raw, type);\n        } catch (IllegalArgumentException ex) {\n            throw new IllegalArgumentException(\n                    \"Failed to coerce parameter '\" + param.name() + \"' to type \" + type.getSimpleName(), ex);\n        }\n    }\n\n    /**\n     * Parses a {@link Param}'s string default value into the declared Java type.\n     *\n     * <p>\n     * Handles primitives, boxed types, {@link String}, {@link Boolean}, and enums\n     * explicitly, mirroring the validation logic in {@link Param}. The\n     * {@link ObjectMapper#readValue} fallback exists as a safety net but is not\n     * expected to be reached in practice, since {@link Param} construction rejects\n     * defaults for non-primitive/boxed/String/Boolean/enum types.\n     *\n     * @param <T>\n     *            the target Java type\n     * @param param\n     *            the parameter descriptor carrying the default value","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/rpc/ParamCoercion.java#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the cause (ex.getCause()) for Jackson's detailed mismatch report and align the argument with the declared type","Send arguments as the correct JSON shape matching the tool's parameter schema","Upgrade client and server so both sides use the same tool schema version","Catch IllegalArgumentException, wrap with context, and fail fast with the parameter name included"],"exampleFix":"// before\nargs.put(\"options\", \"a,b\"); // String where List expected\n// after\nargs.put(\"options\", java.util.List.of(\"a\", \"b\"));","handlingStrategy":"try-catch","validationCode":"try { mapper.convertValue(raw, declaredType); } catch (IllegalArgumentException e) { /* fix payload before invoking */ }","typeGuard":"null","tryCatchPattern":"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); }","preventionTips":["Keep client and server tool schema versions in sync","Build arguments from the tool's generated schema, not ad-hoc maps","Pre-convert nested JSON Maps into the declared POJO types"],"tags":["java","rpc","jackson","coercion"],"backgroundTag":"schema-validation-failed","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}