conductor-oss/conductor · error · NotFoundException

No such workflow found by name: %s, version: %d

Error message

No such workflow found by name: %s, version: %d

What it means

Thrown by WorkflowServiceImpl.startWorkflow(name, version, ...) when metadataService.getWorkflowDef returns null, i.e. no WorkflowDef with that name (and version if specified) exists. Maps to HTTP 404. The workflow cannot be started because its definition is unknown to the metadata store.

Source

Thrown at core/src/main/java/com/netflix/conductor/service/WorkflowServiceImpl.java:121

     * Start a new workflow. Returns the ID of the workflow instance that can be later used for
     * tracking.
     *
     * @param name Name of the workflow you want to start.
     * @param version Version of the workflow you want to start.
     * @param correlationId CorrelationID of the workflow you want to start.
     * @param priority Priority of the workflow you want to start.
     * @param input Input to the workflow you want to start.
     * @return the id of the workflow instance that can be use for tracking.
     */
    public String startWorkflow(
            String name,
            Integer version,
            String correlationId,
            Integer priority,
            Map<String, Object> input) {
        WorkflowDef workflowDef = metadataService.getWorkflowDef(name, version);
        if (workflowDef == null) {
            throw new NotFoundException(
                    "No such workflow found by name: %s, version: %d", name, version);
        }

        StartWorkflowInput startWorkflowInput = new StartWorkflowInput();
        startWorkflowInput.setName(workflowDef.getName());
        startWorkflowInput.setVersion(workflowDef.getVersion());
        startWorkflowInput.setCorrelationId(correlationId);
        startWorkflowInput.setPriority(priority);
        startWorkflowInput.setWorkflowInput(input);

        return workflowExecutor.startWorkflow(startWorkflowInput);
    }

    /**
     * Lists workflows for the given correlation id.
     *
     * @param name Name of the workflow.
     * @param correlationId CorrelationID of the workflow you want to start.

View on GitHub (pinned to cf7c3e4a8a)

Solutions

  1. List available definitions: GET /api/metadata/workflow to confirm name/version exist.
  2. Register the workflow definition (PUT /api/metadata/workflow) before starting.
  3. Omit version to start the latest registered version if exact version is not required.
  4. Verify you target the correct conductor instance/environment.

Example fix

// before
String id = workflowService.startWorkflow("orderFlow", 3, corrId, 0, input); // 404

// after
WorkflowDef def = metadataService.getWorkflowDef("orderFlow", null);
String id = workflowService.startWorkflow(def.getName(), def.getVersion(), corrId, 0, input);
Defensive patterns

Strategy: validation

Validate before calling

WorkflowDef def = metadataService.getWorkflowDef(name, version);
// getWorkflowDef itself throws NotFoundException; to pre-check without throwing:
Optional<WorkflowDef> opt = metadataService.findWorkflowDef(name, version);
if (opt.isEmpty()) { /* register or abort */ }

Try / catch

try {
    return workflowService.startWorkflow(name, version, corrId, priority, input);
} catch (NotFoundException e) {
    // workflow def missing; register then retry, or surface to caller
}

Prevention

When it happens

Trigger: POST /api/workflow with a workflow name/version that is not registered. Calling startWorkflow(name, version, correlationId, priority, input) directly where name or version does not match a registered WorkflowDef.

Common situations: Workflow definition not deployed to the target environment; version requested is higher than what exists; name typo; definition registered in a different namespace/cluster; race where start is called before registration completes.

Related errors

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