alibaba/spring-ai-alibaba · error · RuntimeException
Schema validation failed:
Error message
Schema validation failed:
What it means
Generic catch-all in the tool-call validator in PromptRunServiceImpl: any non-Jackson exception during schema setup or validation (e.g. invalid schema document, null nodes, factory errors) is wrapped as "Schema validation failed". Unlike error 490/491 this is not an input-data problem but a failure validating, often due to a malformed or unsupported schema.
Source
Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/service/impl/PromptRunServiceImpl.java:258
try {
JsonNode schemaNode = objectMapper.readTree(inputSchema);
JsonNode dataNode = objectMapper.valueToTree(inputMap);
JsonSchemaFactory factory = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V7);
JsonSchema schema = factory.getSchema(schemaNode);
Set<ValidationMessage> errors = schema.validate(dataNode);
if (!errors.isEmpty()) {
throw new IllegalArgumentException("Tool Calls Invalid input data: " + errors);
}
return this.output;
} catch (JsonProcessingException e) {
log.error("JSON 处理失败: ", e);
throw new RuntimeException("JSON processing failed: " + e.getMessage(), e);
} catch (Exception e) {
log.error("JSON 处理失败: ", e);
throw new RuntimeException("Schema validation failed: " + e.getMessage(), e);
}
}
}
}
View on GitHub (pinned to f82da0b50f)
Solutions
- Inspect the wrapped cause (e.getCause()) — the generic message hides the real exception.
- Validate the schema JSON itself with a draft-07 schema validator/linter.
- Confirm the schema node is parsed (readTree) not a raw string and is non-null.
- Pin the schema to SpecVersion.VersionFlag.V7-compatible keywords only.
Example fix
// before: raw string passed as schema JsonSchema schema = factory.getSchema(rawSchemaString); // after: parse first JsonNode schemaNode = mapper.readTree(rawSchemaString); JsonSchema schema = factory.getSchema(schemaNode);
Defensive patterns
Strategy: try-catch
Validate before calling
JsonNode schemaNode = mapper.readTree(schemaJson);
if (!schemaNode.isObject() || schemaNode.path("type").isMissingNode()) throw new IllegalStateException("Invalid schema document"); Try / catch
catch (Exception e) {
Throwable root = e;
while (root.getCause() != null) root = root.getCause();
log.error("Schema validation setup failed, root cause: {}", root.getMessage(), root);
throw new RuntimeException("Schema validation failed: " + e.getMessage(), e);
} Prevention
- Lint tool schemas against JSON Schema draft-07 before storing them
- Always unwrap and log the root cause of the generic catch
- Parse schema strings into JsonNode before passing to JsonSchemaFactory
- Pin schema documents to V7 keywords supported by VersionFlag.V7
When it happens
Trigger: factory.getSchema(schemaNode) receives a schema that is not a valid JSON Schema draft-07 document (e.g. wrong top-level type, unsupported keywords), or dataNode/schemaNode is null, or any unexpected runtime exception occurs in the validation block.
Common situations: Tool schema authored by hand with a typo (e.g. "type": "strng"); schema stored as a string but passed unparsed; using draft-07 keywords invalid per VersionFlag.V7; null schema because configuration was not loaded.
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
AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09).
Data as JSON: /api/errors/10d671adc972bc7b.
Report an issue: GitHub.