{"record":{"id":"ad32c2b5921e3fd3","repo":"conductor-oss/conductor","slug":"usx-message","errorCode":null,"errorMessage":"${usx.message}","messagePattern":"\\$\\{usx\\.message\\}","errorType":"exception","errorClass":"IllegalStateException","httpStatus":500,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/MultiAgentCompiler.java","lineNumber":2619,"sourceCode":"        List<Map<String, Object>> parentToolsAsMaps = new ArrayList<>();\n        for (ToolConfig t : parentTools) {\n            // /dg #1: reject schemas using JSON-Schema features the runtime\n            // INLINE validator silently ignores ($ref, allOf, anyOf, oneOf,\n            // format, if/then/else, etc.). Without this check users got\n            // permissive runtime validation — the schema appears to declare\n            // constraints but the validator never fires them. Fail at\n            // agent-compile time with the exact offending keyword + path.\n            if (t.getInputSchema() != null) {\n                try {\n                    SchemaSubsetValidator.validate(\n                            t.getInputSchema(),\n                            \"PLAN_EXECUTE '\"\n                                    + config.getName()\n                                    + \"': tool '\"\n                                    + t.getName()\n                                    + \"' inputSchema\");\n                } catch (SchemaSubsetValidator.UnsupportedSchemaException usx) {\n                    throw new IllegalStateException(usx.getMessage(), usx);\n                }\n            }\n            try {\n                @SuppressWarnings(\"unchecked\")\n                Map<String, Object> m = MAPPER.convertValue(t, Map.class);\n                parentToolsAsMaps.add(m);\n            } catch (Exception e) {\n                // /dg #7: fail-closed on ALL serialization failures, not just\n                // guardrailed ones. Previously a non-guardrailed tool was\n                // silently dropped from parentToolsByName with only a WARN,\n                // which meant ``knownToolNames`` still allowed the tool but\n                // PAC had no schema / inputSchema / guardrail context — a\n                // generate-op output landed in a bare SIMPLE with no\n                // validation. Treat the divergence as a compile error so the\n                // user fixes the ToolConfig (typically a non-Jackson-friendly\n                // value in inputSchema or config) instead of shipping a\n                // half-configured tool. Guardrailed tools get the longer\n                // diagnostic since the failure mode there is more dangerous.","sourceCodeStart":2601,"sourceCodeEnd":2637,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/MultiAgentCompiler.java#L2601-L2637","documentation":"Thrown as IllegalStateException wrapping a SchemaSubsetValidator.UnsupportedSchemaException. The validator checks that a tool's inputSchema only uses JSON Schema keywords the runtime INLINE validator actually handles (a Draft-07 subset). Unsupported keywords like $ref, allOf, oneOf, format, etc. would silently pass at runtime, producing permissive validation. The message is forwarded verbatim from the validator.","triggerScenarios":"A PLAN_EXECUTE-strategy agent with a tool whose inputSchema (ToolConfig.getInputSchema()) contains an unsupported JSON Schema keyword. The supported set is: type, properties, required, additionalProperties, items, enum, minLength, maxLength, pattern, minimum, maximum, minItems, maxItems, title, description, examples, default, $schema, $id. Keywords like $ref, allOf, anyOf, oneOf, format, const, if/then/else, patternProperties, and others are rejected.","commonSituations":"Using a JSON Schema generated by Pydantic, FastAPI, or OpenAPI that includes $ref/$defs (very common with Pydantic v2), format constraints (e.g., 'format': 'date-time'), or allOf/anyOf composition. These are valid Draft-07 but the runtime validator ignores them silently, so the compiler rejects them at compile time.","solutions":["Inline all $ref references — replace $ref pointers with their resolved schema objects directly.","Replace format constraints (e.g., 'format': 'email') with explicit pattern regex or remove them.","Flatten allOf/anyOf/oneOf compositions into a single object schema.","Replace const with enum: [value].","Remove patternProperties, readOnly, writeOnly, and other non-supported keywords."],"exampleFix":"// before: inputSchema with $ref and format\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"email\": {\"type\": \"string\", \"format\": \"email\"},\n    \"user\": {\"$ref\": \"#/$defs/User\"}\n  },\n  \"$defs\": {\"User\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}}\n}\n// after: inlined, format removed, $ref resolved\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"email\": {\"type\": \"string\", \"pattern\": \"^[^@]+@[^@]+\\\\.[^@]+$\"},\n    \"user\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}\n  }\n}","handlingStrategy":"validation","validationCode":"// Pre-validate all tool input schemas before compiling\nprivate static final Set<String> SUPPORTED = new LinkedHashSet<>(Arrays.asList(\n    \"type\", \"properties\", \"required\", \"additionalProperties\", \"items\",\n    \"enum\", \"minLength\", \"maxLength\", \"pattern\", \"minimum\", \"maximum\",\n    \"minItems\", \"maxItems\", \"title\", \"description\", \"examples\",\n    \"default\", \"$schema\", \"$id\"));\n\nvoid preValidateSchemas(List<ToolConfig> tools) {\n    for (ToolConfig t : tools) {\n        if (t.getInputSchema() != null) {\n            SchemaSubsetValidator.validate(t.getInputSchema(),\n                \"tool '\" + t.getName() + \"' inputSchema\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    SchemaSubsetValidator.validate(tool.getInputSchema(), location);\n} catch (SchemaSubsetValidator.UnsupportedSchemaException e) {\n    // rewrite the schema to use only supported keywords, then retry\n    log.warn(\"Schema rejected: {}\", e.getMessage());\n    throw e;\n}","preventionTips":["Run SchemaSubsetValidator.validate() in a unit test against every tool schema before deploying.","Avoid $ref and $defs in tool schemas — inline everything.","Pydantic-generated schemas commonly use $ref/allOf — flatten them before use.","Do not use 'format' — replace with 'pattern' regex."],"tags":["plan-execute","json-schema","schema-validation","input-schema","agentspan"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}