nektos/act · error

The runs.using key in action.yml must be one of: %v, got %s

Error message

The runs.using key in action.yml must be one of: %v, got %s

What it means

Returned by ActionRunsUsing.UnmarshalYAML when an action's metadata `runs.using` key (after lowercasing) is not one of node12, node16, node20, node24, docker, or composite. This is the model-level gate that runs during YAML decoding of action.yml/action.yaml, before the action is ever executed.

Source

Thrown at pkg/model/action.go:27

	"gopkg.in/yaml.v3"
)

// ActionRunsUsing is the type of runner for the action
type ActionRunsUsing string

func (a *ActionRunsUsing) UnmarshalYAML(unmarshal func(interface{}) error) error {
	var using string
	if err := unmarshal(&using); err != nil {
		return err
	}

	// Force input to lowercase for case insensitive comparison
	format := ActionRunsUsing(strings.ToLower(using))
	switch format {
	case ActionRunsUsingNode24, ActionRunsUsingNode20, ActionRunsUsingNode16, ActionRunsUsingNode12, ActionRunsUsingDocker, ActionRunsUsingComposite:
		*a = format
	default:
		return fmt.Errorf("The runs.using key in action.yml must be one of: %v, got %s", []string{
			ActionRunsUsingComposite,
			ActionRunsUsingDocker,
			ActionRunsUsingNode12,
			ActionRunsUsingNode16,
			ActionRunsUsingNode20,
			ActionRunsUsingNode24,
		}, format)
	}
	return nil
}

const (
	// ActionRunsUsingNode12 for running with node12
	ActionRunsUsingNode12 = "node12"
	// ActionRunsUsingNode16 for running with node16
	ActionRunsUsingNode16 = "node16"
	// ActionRunsUsingNode20 for running with node20
	ActionRunsUsingNode20 = "node20"

View on GitHub (pinned to 4f41128141)

Solutions

1. Set `using:` to a supported value: node20, node24, node12, node16, docker, or composite.
2. For JavaScript actions on an unsupported runtime (e.g. node18-only), use node20 — GitHub-compatible and accepted by act.
3. If the action is third-party, pin a tag/commit of that action whose action.yml uses a supported runtime, or vendor and patch it locally.

Example fix

# before
runs:
  using: 'node18'
  main: 'index.js'
# after
runs:
  using: 'node20'
  main: 'index.js'

var validUsing = map[string]bool{"node12": true, "node16": true, "node20": true, "node24": true, "docker": true, "composite": true}
func checkUsing(ymlPath string) error {
    var a struct{ Runs struct{ Using string `yaml:"using"` } `yaml:"runs"` }
    b, _ := os.ReadFile(ymlPath)
    if err := yaml.Unmarshal(b, &a); err != nil { return err }
    if !validUsing[strings.ToLower(a.Runs.Using)] {
        return fmt.Errorf("unsupported using %q", a.Runs.Using)
    }
    return nil
}

When it happens

Trigger: A local or remote action declares `using: node18` (never a valid value), `using: node` (truncated), or a typo like `using: compsite`. Because comparison is case-insensitive after ToLower, `Node20` is fine but any unrecognized string fails.

Common situations: Actions authored for GitHub runner versions act does not support yet; typos in hand-written action.yml; actions generated by tooling that emits newer/older runtime identifiers; copying an action.yml template and forgetting to update the using key.

Related errors

• workflow is not valid. '%s': %w
• Actions YAML Schema Validation Error detected:\nFor more inf
• The runs.using key must be one of: %v, got %s
• Invalid run/uses syntax for job:%s step:%+v
• ErrShortRef

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