{"record":{"id":"dfd3e84cf091e7b8","repo":"iflytek/astron-agent","slug":"bad-request","errorCode":"BAD_REQUEST","errorMessage":"HTTP message not readable exception: {}","messagePattern":"HTTP message not readable exception: (.+?)","errorType":"http","errorClass":"HttpMessageNotReadableException","httpStatus":400,"severity":"warning","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/config/exception/handler/GlobalExceptionHandler.java","lineNumber":91,"sourceCode":"        String messageCode = \"parameter.error\";\n        log.warn(\"Parameter type mismatch exception: {}\", messageCode, e);\n        return ApiResult.error(ResponseEnum.PARAMETER_ERROR.getCode(), messageCode);\n    }\n\n    /** Handle missing request parameter exceptions */\n    @ExceptionHandler(MissingServletRequestParameterException.class)\n    @ResponseStatus(HttpStatus.BAD_REQUEST)\n    public ApiResult<Void> handleMissingServletRequestParameterException(MissingServletRequestParameterException e) {\n        String messageCode = \"parameter.missing\";\n        log.warn(\"Missing request parameter exception: {}\", messageCode);\n        return ApiResult.error(ResponseEnum.PARAMETER_ERROR.getCode(), messageCode);\n    }\n\n    /** Handle HTTP message not readable exceptions */\n    @ExceptionHandler(HttpMessageNotReadableException.class)\n    @ResponseStatus(HttpStatus.BAD_REQUEST)\n    public ApiResult<Void> handleHttpMessageNotReadableException(HttpMessageNotReadableException e) {\n        log.warn(\"HTTP message not readable exception: {}\", e.getMessage(), e);\n        return ApiResult.error(ResponseEnum.BAD_REQUEST.getCode(), \"parameter.illegal\");\n    }\n\n    /** Handle HTTP request method not supported exceptions */\n    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)\n    @ResponseStatus(HttpStatus.METHOD_NOT_ALLOWED)\n    public ApiResult<Void> handleHttpRequestMethodNotSupportedException(HttpRequestMethodNotSupportedException e) {\n        String messageCode = \"http.method.not.supported\";\n        log.warn(\"HTTP request method not supported exception: {}\", messageCode, e);\n        return ApiResult.error(ResponseEnum.METHOD_NOT_ALLOWED.getCode(), messageCode);\n    }\n\n    /** Handle handler not found exceptions */\n    @ExceptionHandler(NoHandlerFoundException.class)\n    @ResponseStatus(HttpStatus.NOT_FOUND)\n    public ApiResult<Void> handleNoHandlerFoundException(NoHandlerFoundException e) {\n        String messageCode = \"http.url.not.found\";\n        log.warn(\"Handler not found exception: {}\", messageCode, e);","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/config/exception/handler/GlobalExceptionHandler.java#L73-L109","documentation":"Spring MVC throws HttpMessageNotReadableException when the request body cannot be deserialized into the @RequestBody target type. The handler returns HTTP 400 with BAD_REQUEST code and message 'parameter.illegal'. Commonly caused by malformed JSON or JSON that does not match the target DTO.","triggerScenarios":"POST/PUT with @RequestBody where the body is invalid JSON, empty, wrong content type, or fields have incompatible types (e.g. string where an int/enum is expected).","commonSituations":"Client forgets Content-Type: application/json; sending form-encoded data to a JSON endpoint; JSON field names don't match the DTO; sending 'null'/'undefined' as body; special characters or BOM breaking the JSON parser.","solutions":["Check e.getMessage() in the server log for the Jackson offset message; fix the JSON at the indicated character/line.","Set the request header Content-Type: application/json on POST/PUT calls with a body.","Validate the payload against the DTO field names and types; align client serialization with the Java class.","Ensure the body is non-empty and valid JSON (use a JSON linter or JSON.stringify on the client).","If using a custom Jackson ObjectMapper/enum deserialization, verify the sent enum values are accepted."],"exampleFix":"// before\nfetch('/api/agent', { method: 'POST', body: JSON.stringify(data) }) // no content-type -> not readable\n\n// after\nfetch('/api/agent', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data) })","handlingStrategy":"validation","validationCode":"// client-side validation before sending a JSON body\nconst body = JSON.stringify(payload); // throws SyntaxError on circular refs handled below\nfunction assertSerializable(o) { JSON.stringify(o); return o; }\nconst safePayload = assertSerializable(payload);","typeGuard":"function isValidJson(text) {\n  try { const v = JSON.parse(text); return v !== undefined && v !== null; } catch { return false; }\n}","tryCatchPattern":"try {\n  const res = await api.post('/api/agent', payload, { headers: { 'Content-Type': 'application/json' } });\n} catch (e) {\n  if (e.response?.status === 400 && e.response?.data?.message === 'parameter.illegal') {\n    console.error('Request body is not readable JSON / does not match DTO');\n  } else throw e;\n}","preventionTips":["Always set Content-Type: application/json for JSON bodies.","Validate payloads against the DTO schema (zod/ajv + generated schema) before sending.","Never send undefined or empty bodies to @RequestBody endpoints.","Mirror enum/field names exactly between client and Java DTO; regenerate types when the backend changes."],"tags":["http","json","spring-mvc","deserialization"],"backgroundTag":"json-parse-error","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}