conductor-oss/conductor · critical · IllegalStateException

Skill registry is not available

Error message

Skill registry is not available

What it means

Thrown by AgentService.resolveConfig when the request uses framework='skill' with a skillRef but the SkillRegistryService bean is null (not wired). This means the agentspan module was built/deployed without the skill registry integration, so skill references cannot be resolved. IllegalStateException maps to HTTP 500 — it is a configuration/deployment problem, not a caller input error.

Source

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

            }
        }
    }

    // ── Config resolution ─────────────────────────────────────────

    /**
     * Resolve the AgentConfig from a AgentStartRequest. If {@code framework} is set, normalize the
     * raw config via the appropriate normalizer. Otherwise, use the native {@code agentConfig}
     * field directly.
     */
    private AgentConfig resolveConfig(AgentStartRequest request) {
        if (request.getFramework() != null && !request.getFramework().isEmpty()) {
            log.debug("Normalizing framework '{}' agent config", request.getFramework());
            if ("skill".equals(request.getFramework())
                    && request.getRawConfig() == null
                    && request.getSkillRef() != null) {
                if (skillRegistryService == null) {
                    throw new IllegalStateException("Skill registry is not available");
                }
                request.setRawConfig(skillRegistryService.resolveRawConfig(request.getSkillRef()));
            }
            return normalizerRegistry.normalize(request.getFramework(), request.getRawConfig());
        }
        if (request.getAgentConfig() == null) {
            throw new IllegalArgumentException(
                    "agentConfig is required when framework is not specified");
        }
        return request.getAgentConfig();
    }

    // ── SSE Streaming ──────────────────────────────────────────────

    /** Open an SSE stream for an agent execution. Replays missed events on reconnect. */
    public SseEmitter openStream(String executionId, Long lastEventId) {
        log.info("Opening SSE stream for execution {} (lastEventId={})", executionId, lastEventId);
        workflowService.getExecutionStatus(executionId, false);

View on GitHub (pinned to cf7c3e4a8a)

Solutions

  1. Ensure the SkillRegistryService bean is available (include the skill-registry module and activate its conditional property).
  2. If skills are not supported in this deployment, do not use framework=skill — use framework=conductor with an inline agentConfig instead.
  3. Check the Spring context / bean wiring for SkillRegistryService.

Example fix

// before (framework=skill but no registry)
AgentStartRequest req = AgentStartRequest.builder()
    .framework("skill")
    .skillRef("my-skill")
    .prompt("hello")
    .build();
service.start(req); // -> IllegalStateException

// after (option A: enable the registry)
// application.properties: conductor.integrations.ai.skills.enabled=true
// after (option B: use inline config instead)
AgentStartRequest req = AgentStartRequest.builder()
    .agentConfig(myConfig)
    .prompt("hello")
    .build();
Defensive patterns

Strategy: try-catch

Validate before calling

// Before using framework=skill, verify the registry is wired
if (skillRegistryService == null && "skill".equals(request.getFramework())) {
    throw new IllegalStateException(
        "Skill registry not available; cannot resolve skillRef");
}

Try / catch

try {
    service.start(request);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Skill registry is not available")) {
        // Deployment issue — fall back to inline agentConfig
        log.error("Skill registry not wired; use inline config instead", e);
    }
}

Prevention

When it happens

Trigger: Starting an agent with framework=skill and skillRef set, but the SkillRegistryService is not on the classpath or not injected; the conditional bean for SkillRegistryService was not activated.

Common situations: Production deployment excludes the skill-registry module; Spring profile or conditional property for SkillRegistryService is not enabled; a custom build strips the skill registry dependency.

Related errors

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