{"record":{"id":"4c965a811a6a2c5d","repo":"conductor-oss/conductor","slug":"registered-agent-definition-is-missing-metadata-ag","errorCode":null,"errorMessage":"Registered agent definition is missing metadata.agentDef: ${name} v${version}","messagePattern":"Registered agent definition is missing metadata\\.agentDef: (.+?) v(.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":500,"severity":"critical","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java","lineNumber":334,"sourceCode":"    }\n\n    private AgentConfig resolveStoredConfig(WorkflowDef def) {\n        Map<String, Object> agentDef = storedAgentDef(def);\n        Object sdkValue = def.getMetadata().get(\"agent_sdk\");\n        String sdk = sdkValue instanceof String ? (String) sdkValue : \"conductor\";\n        if (sdk.isBlank() || \"conductor\".equals(sdk)) {\n            return MAPPER.convertValue(agentDef, AgentConfig.class);\n        }\n        return normalizerRegistry.normalize(sdk, agentDef);\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private Map<String, Object> storedAgentDef(WorkflowDef def) {\n        Map<String, Object> metadata = def.getMetadata();\n        if (metadata != null && metadata.get(\"agentDef\") instanceof Map<?, ?>) {\n            return (Map<String, Object>) metadata.get(\"agentDef\");\n        }\n        throw new IllegalStateException(\n                \"Registered agent definition is missing metadata.agentDef: \"\n                        + def.getName()\n                        + \" v\"\n                        + def.getVersion());\n    }\n\n    // ── Agent discovery ─────────────────────────────────────────────\n\n    /** List all registered agents (workflow defs with agent_sdk metadata). */\n    @SuppressWarnings(\"unchecked\")\n    public List<AgentSummary> listAgents() {\n        // Use the portable getAllWorkflowDefs() (present across Conductor cores, incl. orkes'\n        // vendored oss-core which lacks getAllWorkflowDefsLatestVersions()) and reduce to the\n        // latest version per name ourselves.\n        Map<String, WorkflowDef> latestByName = new HashMap<>();\n        for (WorkflowDef d : metadataDAO.getAllWorkflowDefs()) {\n            latestByName.merge(d.getName(), d, (a, b) -> a.getVersion() >= b.getVersion() ? a : b);\n        }","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java#L316-L352","documentation":"Thrown by AgentService.storedAgentDef (private) when a workflow def that classified as an agent is missing the metadata.agentDef map. This is a data-integrity violation: the def has agent_sdk metadata (so it classifies as agent) but lacks the embedded agentDef blob needed to reconstruct the AgentConfig. IllegalStateException maps to HTTP 500 — this indicates corrupted or manually-edited metadata, not a user input error.","triggerScenarios":"An agent was registered by directly writing to MetadataDAO without going through deploy()/compile() (which stamp agentDef); a migration or metadata edit stripped the agentDef key; the def was created by an older AgentService version that used a different metadata key.","commonSituations":"Manual DB insertion of a workflow def with agent_sdk but no agentDef; partial metadata update that overwrote the metadata map without preserving agentDef; upgrade from an older Conductor-Agents version that stored config differently.","solutions":["Redeploy the agent via AgentService.deploy() to regenerate and stamp the full metadata including agentDef.","If the agentDef is recoverable, patch the workflow def metadata to include it and update via metadataService.updateWorkflowDef.","Delete the corrupted def via deleteAgent and redeploy from the original agent config source."],"exampleFix":"// The fix is operational, not code-level:\n// 1. Delete the corrupted agent definition\nagentService.deleteAgent(\"my_agent\", null);\n// 2. Redeploy so metadata.agentDef is stamped correctly\nagentService.deploy(originalAgentStartRequest);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    service.start(request);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"missing metadata.agentDef\")) {\n        // Data corruption — redeploy the agent to repair metadata\n        log.error(\"Corrupted agent metadata, redeploy required\", e);\n        redeployAgent(request.getName());\n    }\n}","preventionTips":["Always deploy agents via AgentService.deploy() — never inject defs directly into MetadataDAO.","Run a metadata audit after upgrades to confirm agentDef is present on all agent defs.","Add a startup health check that validates all classified agents have agentDef."],"tags":["data-integrity","metadata","agent","illegal-state"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}