{"record":{"id":"4604943b088919cb","repo":"conductor-oss/conductor","slug":"no-agent-definition-found-for-name","errorCode":null,"errorMessage":"No agent definition found for: ${name}","messagePattern":"No agent definition found for: (.+?)","errorType":"http","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java","lineNumber":873,"sourceCode":"        if (version != null) {\n            def =\n                    metadataDAO\n                            .getWorkflowDef(name, version)\n                            .orElseThrow(\n                                    () ->\n                                            new NotFoundException(\n                                                    \"Agent not found: \" + name + \" v\" + version));\n        } else {\n            def =\n                    metadataDAO\n                            .getLatestWorkflowDef(name)\n                            .orElseThrow(() -> new NotFoundException(\"Agent not found: \" + name));\n        }\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 NotFoundException(\"No agent definition found for: \" + name);\n    }\n\n    public void deleteAgent(String name, Integer version) {\n        if (version != null) {\n            metadataDAO.removeWorkflowDef(name, version);\n        } else {\n            // Remove latest version\n            WorkflowDef def =\n                    metadataDAO\n                            .getLatestWorkflowDef(name)\n                            .orElseThrow(() -> new NotFoundException(\"Agent not found: \" + name));\n            metadataDAO.removeWorkflowDef(name, def.getVersion());\n        }\n    }\n\n    /**\n     * Persist an agent-generated workflow with the metadata lifecycle used by normal workflow\n     * definitions. Direct DAO updates bypass {@link MetadataService} and leave a newly deployed","sourceCodeStart":855,"sourceCodeEnd":891,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java#L855-L891","documentation":"Thrown by AgentService.getAgentDef when a workflow definition is found by name/version but its metadata.agentDef is not present (or not a Map). This is distinct from error [46] (IllegalStateException) — getAgentDef is the public read API for retrieving an agent's stored definition, and it reports the missing agentDef as a NotFoundException (HTTP 404) since, from the caller's perspective, the agent definition does not exist in usable form.","triggerScenarios":"Calling getAgentDef for a workflow that was registered without going through deploy()/compile(); the metadata.agentDef key was stripped or renamed; the def predates the agentDef-stamping feature.","commonSituations":"Querying an agent that was manually registered as a plain workflow; metadata migration altered the key name; the agent was deployed by an older version that did not stamp agentDef into metadata.","solutions":["Redeploy the agent via AgentService.deploy() to stamp metadata.agentDef.","If the raw config is available, use it to reconstruct and redeploy.","Delete the incomplete def via deleteAgent and redeploy cleanly."],"exampleFix":"// Operational fix:\n// 1. Check what metadata exists\nmetadataDAO.getWorkflowDef(name, version).ifPresent(d ->\n    log.info(\"metadata keys: {}\", d.getMetadata().keySet()));\n// 2. Redeploy to stamp agentDef\nagentService.deploy(originalRequest);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Map<String, Object> def = agentService.getAgentDef(name, version);\n    // use def\n} catch (NotFoundException e) {\n    if (e.getMessage().contains(\"No agent definition found\")) {\n        // metadata.agentDef missing — redeploy to repair\n        log.error(\"Agent {} missing agentDef metadata, redeploy required\", name);\n    }\n}","preventionTips":["Deploy agents via deploy() so metadata.agentDef is always stamped.","Audit agent metadata after upgrades.","Treat this 404 as a data-integrity signal, not a missing-resource signal."],"tags":["not-found","agent-def","metadata","public-api"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}