{"record":{"id":"da67b824328a588e","repo":"spring-projects/spring-ai","slug":"failed-to-parse-json-schema-da67b8","errorCode":null,"errorMessage":"Failed to parse JSON schema","messagePattern":"Failed to parse JSON schema","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/advisor/StructuredOutputValidationAdvisor.java","lineNumber":97,"sourceCode":"\t\tAssert.notNull(outputJsonSchema, \"outputJsonSchema must not be null\");\n\t\tAssert.isTrue(advisorOrder > BaseAdvisor.HIGHEST_PRECEDENCE && advisorOrder < BaseAdvisor.LOWEST_PRECEDENCE,\n\t\t\t\t\"advisorOrder must be between HIGHEST_PRECEDENCE and LOWEST_PRECEDENCE\");\n\t\tAssert.isTrue(maxRepeatAttempts >= 0, \"repeatAttempts must be greater than or equal to 0\");\n\t\tAssert.notNull(jsonMapper, \"jsonMapper must not be null\");\n\n\t\tthis.advisorOrder = advisorOrder;\n\t\tthis.jsonMapper = jsonMapper;\n\n\t\tif (logger.isDebugEnabled()) {\n\t\t\tlogger.debug(\"Generated JSON Schema:\\n\" + outputJsonSchema);\n\t\t}\n\n\t\tJsonNode schemaNode;\n\t\ttry {\n\t\t\tschemaNode = jsonMapper.readTree(outputJsonSchema);\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new IllegalArgumentException(\"Failed to parse JSON schema\", e);\n\t\t}\n\n\t\tSchemaRegistry schemaRegistry = SchemaRegistry.withDefaultDialect(SpecificationVersion.DRAFT_2020_12);\n\t\tthis.jsonSchema = schemaRegistry.getSchema(schemaNode);\n\n\t\tthis.maxRepeatAttempts = maxRepeatAttempts;\n\t}\n\n\t@SuppressWarnings(\"null\")\n\t@Override\n\tpublic String getName() {\n\t\treturn \"Structured Output Validation Advisor\";\n\t}\n\n\t@Override\n\tpublic int getOrder() {\n\t\treturn this.advisorOrder;\n\t}","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/advisor/StructuredOutputValidationAdvisor.java#L79-L115","documentation":"StructuredOutputValidationAdvisor's constructor parses the supplied JSON schema string with Jackson (jsonMapper.readTree) and then validates it against JSON Schema draft 2020-12 via SchemaRegistry. If the string is not parseable JSON, it throws IllegalArgumentException('Failed to parse JSON schema', e) with the underlying parse error as cause.","triggerScenarios":"Constructing StructuredOutputValidationAdvisor with an outputJsonSchema string that is malformed JSON: truncated string, comments/trailing commas, a Java string template placeholder left unsubstituted, or an empty/whitespace value that passed earlier checks.","commonSituations":"Hand-written schemas with trailing commas, schema loaded from a properties/env var with quoting issues, reading the schema file with wrong encoding so the content is garbled, or generating the schema dynamically and injecting invalid text.","solutions":["Validate the schema string with a JSON parser before constructing the advisor (read e.getCause() for the exact syntax error position).","Generate the schema with JsonSchemaGenerator.generateForType(Class) instead of hand-writing it.","If loading from a file/classpath, confirm the file content is valid JSON (e.g. with a linter or ObjectMapper.readTree in a startup check).","Fix quoting/escaping issues when the schema comes from env vars or config."],"exampleFix":"// before\nnew StructuredOutputValidationAdvisor(\"{\\\"type\\\":\\\"object\\\",}\", 3); // trailing comma\n// after\nString schema = \"{\\\"type\\\":\\\"object\\\"}\";\nnew ObjectMapper().readTree(schema); // fail fast with a clear error\nnew StructuredOutputValidationAdvisor(schema, 3);","handlingStrategy":"validation","validationCode":"String schema = /* your schema string */;\ntry { new ObjectMapper().readTree(schema); } catch (Exception e) { throw new IllegalStateException(\"invalid JSON schema: \" + e.getMessage()); }","typeGuard":null,"tryCatchPattern":"try { new StructuredOutputValidationAdvisor(schema, 3); } catch (IllegalArgumentException e) { if (e.getMessage().equals(\"Failed to parse JSON schema\")) { log.error(\"schema syntax error\", e.getCause()); } throw e; }","preventionTips":["Validate schema strings with a JSON parser at startup.","Prefer JsonSchemaGenerator.generateForType(Class) over hand-written schemas.","Lint schema files in CI to catch trailing commas/comments."],"tags":["json","schema","structured-output","spring-ai"],"backgroundTag":"json-parse-error","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}