conductor-oss/conductor · error · NotFoundException

No agent definition found for: ${name}

Error message

No agent definition found for: ${name}

What it means

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.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java:873

        if (version != null) {
            def =
                    metadataDAO
                            .getWorkflowDef(name, version)
                            .orElseThrow(
                                    () ->
                                            new NotFoundException(
                                                    "Agent not found: " + name + " v" + version));
        } else {
            def =
                    metadataDAO
                            .getLatestWorkflowDef(name)
                            .orElseThrow(() -> new NotFoundException("Agent not found: " + name));
        }
        Map<String, Object> metadata = def.getMetadata();
        if (metadata != null && metadata.get("agentDef") instanceof Map) {
            return (Map<String, Object>) metadata.get("agentDef");
        }
        throw new NotFoundException("No agent definition found for: " + name);
    }

    public void deleteAgent(String name, Integer version) {
        if (version != null) {
            metadataDAO.removeWorkflowDef(name, version);
        } else {
            // Remove latest version
            WorkflowDef def =
                    metadataDAO
                            .getLatestWorkflowDef(name)
                            .orElseThrow(() -> new NotFoundException("Agent not found: " + name));
            metadataDAO.removeWorkflowDef(name, def.getVersion());
        }
    }

    /**
     * Persist an agent-generated workflow with the metadata lifecycle used by normal workflow
     * definitions. Direct DAO updates bypass {@link MetadataService} and leave a newly deployed

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Redeploy the agent via AgentService.deploy() to stamp metadata.agentDef.
2. If the raw config is available, use it to reconstruct and redeploy.
3. Delete the incomplete def via deleteAgent and redeploy cleanly.

Example fix

// Operational fix:
// 1. Check what metadata exists
metadataDAO.getWorkflowDef(name, version).ifPresent(d ->
    log.info("metadata keys: {}", d.getMetadata().keySet()));
// 2. Redeploy to stamp agentDef
agentService.deploy(originalRequest);

try {
    Map<String, Object> def = agentService.getAgentDef(name, version);
    // use def
} catch (NotFoundException e) {
    if (e.getMessage().contains("No agent definition found")) {
        // metadata.agentDef missing — redeploy to repair
        log.error("Agent {} missing agentDef metadata, redeploy required", name);
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Agent not found: ${name}
• No such task by name %s
• No such taskType found by name: %s
• Execution not found: ${executionId}
• Registered agent definition is missing metadata.agentDef: ${

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/4604943b088919cb. Report an issue: GitHub.