{"record":{"id":"f167e53a3d025409","repo":"conductor-oss/conductor","slug":"agent-not-found-name","errorCode":null,"errorMessage":"Agent not found: ${name}","messagePattern":"Agent not found: (.+?)","errorType":"http","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java","lineNumber":313,"sourceCode":"\n    private WorkflowDef getRegisteredAgent(String name, Integer version) {\n        WorkflowDef def =\n                version != null\n                        ? metadataDAO\n                                .getWorkflowDef(name, version)\n                                .orElseThrow(\n                                        () ->\n                                                new NotFoundException(\n                                                        \"Agent not found: \"\n                                                                + name\n                                                                + \" v\"\n                                                                + version))\n                        : metadataDAO\n                                .getLatestWorkflowDef(name)\n                                .orElseThrow(\n                                        () -> new NotFoundException(\"Agent not found: \" + name));\n        if (!WorkflowClassifiers.isAgent(def.getMetadata())) {\n            throw new NotFoundException(\"Agent not found: \" + name);\n        }\n        return def;\n    }\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<?, ?>) {","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java#L295-L331","documentation":"Thrown by AgentService.getRegisteredAgent (private) when a workflow definition is found by name/version (or latest) but its metadata does not classify as an agent (WorkflowClassifiers.isAgent returns false). This means the name resolves to a regular Conductor workflow, not an agent. NotFoundException maps to HTTP 404. This guard prevents non-agent workflows from being started or resolved through the agent API surface.","triggerScenarios":"Calling start with agentName pointing to a regular (non-agent) workflow definition; the workflow def was registered without agent_sdk/agentDef metadata; a non-agent workflow happens to share the name of a previously-deployed agent.","commonSituations":"Naming collision between a hand-registered workflow and an agent; agent was deployed via a path that did not stamp agent_sdk metadata (e.g. direct MetadataService.registerWorkflowDef bypassing deploy()); the classifier logic changed between versions and a previously-valid agent no longer classifies.","solutions":["Confirm the workflow definition has metadata.agent_sdk or metadata.agentDef set (use getAgentDef to inspect).","Redeploy the agent via AgentService.deploy() which stamps the required metadata.","If the name was meant for a regular workflow, use the standard workflow start API instead of the agent API."],"exampleFix":"// before\nstartRequest.setName(\"my_regular_workflow\");\nservice.start(startRequest); // -> NotFoundException: Agent not found\n\n// after\n// Redeploy as an agent so metadata.agent_sdk is stamped\nservice.deploy(agentStartRequest);\nstartRequest.setName(\"my_agent\");\nservice.start(startRequest);","handlingStrategy":"validation","validationCode":"// Verify the name resolves to an agent before starting\nList<AgentSummary> agents = agentService.listAgents();\nboolean isAgent = agents.stream()\n    .anyMatch(a -> a.getName().equals(name));\nif (!isAgent) {\n    return ResponseEntity.notFound().build();\n}","typeGuard":null,"tryCatchPattern":"try {\n    service.start(request);\n} catch (NotFoundException e) {\n    if (e.getMessage().contains(\"Agent not found\")) {\n        // name does not resolve to an agent def\n        return ResponseEntity.status(404).body(e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Use deploy() to register agents so metadata.agent_sdk is stamped.","Avoid registering plain workflows with names that collide with agent names.","Call listAgents() to verify an agent name before start()."],"tags":["not-found","agent","metadata","classifier"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}