conductor-oss/conductor · critical · IllegalStateException

Registered agent definition is missing metadata.agentDef: ${

Error message

Registered agent definition is missing metadata.agentDef: ${name} v${version}

What it means

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.

Source

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

    }

    private AgentConfig resolveStoredConfig(WorkflowDef def) {
        Map<String, Object> agentDef = storedAgentDef(def);
        Object sdkValue = def.getMetadata().get("agent_sdk");
        String sdk = sdkValue instanceof String ? (String) sdkValue : "conductor";
        if (sdk.isBlank() || "conductor".equals(sdk)) {
            return MAPPER.convertValue(agentDef, AgentConfig.class);
        }
        return normalizerRegistry.normalize(sdk, agentDef);
    }

    @SuppressWarnings("unchecked")
    private Map<String, Object> storedAgentDef(WorkflowDef def) {
        Map<String, Object> metadata = def.getMetadata();
        if (metadata != null && metadata.get("agentDef") instanceof Map<?, ?>) {
            return (Map<String, Object>) metadata.get("agentDef");
        }
        throw new IllegalStateException(
                "Registered agent definition is missing metadata.agentDef: "
                        + def.getName()
                        + " v"
                        + def.getVersion());
    }

    // ── Agent discovery ─────────────────────────────────────────────

    /** List all registered agents (workflow defs with agent_sdk metadata). */
    @SuppressWarnings("unchecked")
    public List<AgentSummary> listAgents() {
        // Use the portable getAllWorkflowDefs() (present across Conductor cores, incl. orkes'
        // vendored oss-core which lacks getAllWorkflowDefsLatestVersions()) and reduce to the
        // latest version per name ourselves.
        Map<String, WorkflowDef> latestByName = new HashMap<>();
        for (WorkflowDef d : metadataDAO.getAllWorkflowDefs()) {
            latestByName.merge(d.getName(), d, (a, b) -> a.getVersion() >= b.getVersion() ? a : b);
        }

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Redeploy the agent via AgentService.deploy() to regenerate and stamp the full metadata including agentDef.
2. If the agentDef is recoverable, patch the workflow def metadata to include it and update via metadataService.updateWorkflowDef.
3. Delete the corrupted def via deleteAgent and redeploy from the original agent config source.

Example fix

// The fix is operational, not code-level:
// 1. Delete the corrupted agent definition
agentService.deleteAgent("my_agent", null);
// 2. Redeploy so metadata.agentDef is stamped correctly
agentService.deploy(originalAgentStartRequest);

try {
    service.start(request);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("missing metadata.agentDef")) {
        // Data corruption — redeploy the agent to repair metadata
        log.error("Corrupted agent metadata, redeploy required", e);
        redeployAgent(request.getName());
    }
}

When it happens

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

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

Related errors

• Agent not found: ${name}
• No agent definition found for: ${name}
• Skill registry is not available
• No pending HUMAN task found in execution {executionId}
• skillRef is required

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