nektos/act · error

Unable to determine how to run job:%s step:%+v

Error message

Unable to determine how to run job:%s step:%+v

What it means

Thrown by stepFactoryImpl.newStep when model.Step.Type() returns a value not covered by the switch in pkg/runner/step_factory.go:16-43. The factory maps each step type (run, uses-action-local, uses-action-remote, uses-docker-url) to a step implementation; this error is the defensive default branch meaning the Step model produced a type the factory cannot execute.

Source

Thrown at pkg/runner/step_factory.go:45

			RunContext: rc,
			readAction: readActionImpl,
			runAction:  runActionImpl,
		}, nil
	case model.StepTypeUsesActionRemote:
		return &stepActionRemote{
			Step:       stepModel,
			RunContext: rc,
			readAction: readActionImpl,
			runAction:  runActionImpl,
		}, nil
	case model.StepTypeUsesDockerURL:
		return &stepDocker{
			Step:       stepModel,
			RunContext: rc,
		}, nil
	}

	return nil, fmt.Errorf("Unable to determine how to run job:%s step:%+v", rc.Run, stepModel)
}

View on GitHub (pinned to 4f41128141)

Solutions

1. Check the printed step (%+v) and job name to identify which YAML step produced the unknown type
2. Verify the step uses either `run:` or `uses: <action|docker://...>` with valid syntax
3. If running a fork or modified build, update step_factory.go's switch to handle the new model.StepType value
4. Ensure pkg/model and pkg/runner come from the same act release (go mod tidy / matching version)

Example fix

# workflow yaml - keep steps to known forms
# before (ambiguous/none):
- name: weird
# after:
- name: run something
  run: echo hi
# or
- name: docker step
  uses: docker://alpine:3.19
  with:
    entrypoint: echo
    args: hi

// Before building execution, ensure every step has a known shape:
for _, s := range job.Steps {
    switch s.Type() {
    case model.StepTypeRun, model.StepTypeUsesActionLocal,
        model.StepTypeUsesActionRemote, model.StepTypeUsesDockerURL:
        // ok
    default:
        return fmt.Errorf("step %q has unsupported type", s.ID)
    }
}

Catch the error from newStep and report job+step identifiers verbatim; do not retry — this is a deterministic configuration failure.

When it happens

Trigger: A workflow step whose YAML produces a model.Step with a Type() value outside the five handled cases. In practice unreachable with the stock model package (StepTypeInvalid is handled at line 17); fires in forks or version-skewed builds where a new model.StepType constant exists but step_factory.go was not updated, or a corrupted/unparseable `uses:`/`run:` combination falls through.

Common situations: Mixing act packages of different versions (pkg/model newer than pkg/runner), vendoring a modified model package that adds step types, or a malformed step that dodges both the Invalid and known-type paths.

Related errors

• expressions are not allowed here
• Missing parameters for %s expected >= %v got %v
• Too many parameters for %s expected <= %v got %v
• Unknown Function Call %s
• Unknown Variable Access %s

AI-assisted analysis of nektos/act@4f41128141 (2026-08-15). Data as JSON: /api/errors/54737e9d25a1824e. Report an issue: GitHub.