conductor-oss/conductor · error · IllegalArgumentException

Cannot find the task definitions for the following tasks use

Error message

Cannot find the task definitions for the following tasks used in workflow: %s

What it means

Thrown by MetadataMapperService.checkNotEmptyDefinitions when one or more SIMPLE-type tasks referenced in a workflow definition do not have a corresponding TaskDef registered in the metadata store. Every SIMPLE task must have a TaskDef registered before the workflow can start. System tasks (SIMPLE type excluded) do not require a TaskDef. This is an IllegalArgumentException that prevents the workflow from starting.

Source

Thrown at core/src/main/java/com/netflix/conductor/core/metadata/MetadataMapperService.java:182

        Utils.checkNotNull(workflowDefinition, "WorkflowDefinition cannot be null");

        // Obtain the names of the tasks with missing definitions
        Set<String> missingTaskDefinitionNames =
                workflowDefinition.collectTasks().stream()
                        .filter(
                                workflowTask ->
                                        workflowTask.getType().equals(TaskType.SIMPLE.name()))
                        .filter(this::shouldPopulateTaskDefinition)
                        .map(WorkflowTask::getName)
                        .collect(Collectors.toSet());

        if (!missingTaskDefinitionNames.isEmpty()) {
            LOGGER.error(
                    "Cannot find the task definitions for the following tasks used in workflow: {}",
                    missingTaskDefinitionNames);
            Monitors.recordWorkflowStartError(
                    workflowDefinition.getName(), WorkflowContext.get().getClientApp());
            throw new IllegalArgumentException(
                    "Cannot find the task definitions for the following tasks used in workflow: "
                            + missingTaskDefinitionNames);
        }
    }

    public TaskModel populateTaskWithDefinition(TaskModel task) {
        Utils.checkNotNull(task, "Task cannot be null");
        populateWorkflowTaskWithDefinition(task.getWorkflowTask());
        return task;
    }

    @VisibleForTesting
    boolean shouldPopulateTaskDefinition(WorkflowTask workflowTask) {
        Utils.checkNotNull(workflowTask, "WorkflowTask cannot be null");
        Utils.checkNotNull(workflowTask.getType(), "WorkflowTask type cannot be null");
        return workflowTask.getTaskDefinition() == null
                && StringUtils.isNotBlank(workflowTask.getName());
    }

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Register the missing TaskDef(s) using the metadata API: POST /api/metadata/taskdefs with the task definition JSON for each missing name listed in the error.
Verify the task names in the workflow definition exactly match the registered TaskDef names (case-sensitive).
If the task is actually a system task, change its type from SIMPLE to the correct system task type (e.g. HTTP, INLINE, SET_VARIABLE).
Re-register the workflow definition after all TaskDefs are in place.

Example fix

// before — workflow references unregistered task
PUT /api/metadata/workflow
{"name":"my_wf","tasks":[{"name":"missing_task","taskReferenceName":"t1","type":"SIMPLE"}]}

// fix — register the task first
POST /api/metadata/taskdefs
[{"name":"missing_task","retryCount":3,"timeoutSeconds":300}]

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight check: verify all SIMPLE task names have registered TaskDefs
Set<String> simpleTaskNames = workflowDef.collectTasks().stream()
    .filter(wt -> "SIMPLE".equals(wt.getType()))
    .map(WorkflowTask::getName)
    .collect(Collectors.toSet());

for (String name : simpleTaskNames) {
    if (metadataDAO.getTaskDef(name) == null) {
        throw new IllegalStateException(
            "TaskDef '" + name + "' is not registered — register it first");
    }
}

Prevention

Register all TaskDefs before registering or starting the workflow that references them.
Use a deployment script that registers TaskDefs first, then workflow definitions.
Add a CI lint step that checks all SIMPLE task references against registered TaskDefs.

When it happens

Trigger: Registering or starting a workflow whose definition references SIMPLE tasks by name, but those task names have no TaskDef entry in the metadata DAO. The error fires during populateWorkflowWithDefinitions or populateTaskDefinitions when the workflow definition is being validated.

Common situations: Registering a workflow definition before registering the TaskDefs for its SIMPLE tasks. Renaming a TaskDef but not updating the workflow definition. Deleting a TaskDef that is still referenced by a deployed workflow. Environment mismatch — TaskDefs exist in one environment but not another.

Related errors

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