Could not find any stages to run. View the valid jobs with `

Error message

Could not find any stages to run. View the valid jobs with `act --list`. Use `act --help` to find how to filter by Job ID/Workflow/Event Name

What it means

After planning (PlanJob for a -j filter or PlanEvent for the detected/specified event), act checks that the resulting Plan has at least one stage. An empty plan means the workflows loaded fine but the filter matched nothing: no job with that ID for the chosen event, or the event itself triggers no workflow. The error text points you to 'act --list' and '--help' for discovering valid IDs and filters.

Source

Thrown at cmd/root.go:560

			// this way user dont have to specify the event.
			log.Debugf("Using first detected workflow event: %s", events[0])
			eventName = events[0]
		} else {
			log.Debugf("Using default workflow event: push")
			eventName = "push"
		}

		// build the plan for this run
		if jobID != "" {
			log.Debugf("Planning job: %s", jobID)
			plan, plannerErr = planner.PlanJob(jobID)
		} else {
			log.Debugf("Planning jobs for event: %s", eventName)
			plan, plannerErr = planner.PlanEvent(eventName)
		}
		if plan != nil {
			if len(plan.Stages) == 0 {
				plannerErr = fmt.Errorf("Could not find any stages to run. View the valid jobs with `act --list`. Use `act --help` to find how to filter by Job ID/Workflow/Event Name")
			}
		}
		if plan == nil && plannerErr != nil {
			return plannerErr
		}

		// check to see if the main branch was defined
		defaultbranch, err := cmd.Flags().GetString("defaultbranch")
		if err != nil {
			return err
		}

		// Check if platforms flag is set, if not, run default image survey
		if len(input.platforms) == 0 {
			cfgFound := false
			cfgLocations := configLocations()
			for _, v := range cfgLocations {
				_, err := os.Stat(v)

View on GitHub (pinned to 4f41128141)

Solutions

Run 'act --list' in the repo root to see valid job IDs and their workflows, then rerun with the exact ID.
Select the right event: 'act pull_request -j <id>' or pass an event file with '-e event.json' matching the workflow's 'on:' triggers.
Check the job's 'if:' condition and 'needs:' chain — dependent or conditionally-skipped jobs may be excluded from the plan.
Confirm you are in the repository root containing .github/workflows/.

Example fix

# before
act -j buld        # typo, plan has no stages

# after
act --list         # discover the real ID: build
act -j build

Defensive patterns

Strategy: validation

Validate before calling

// Confirm a job exists for the event before executing
package main

import (
	"fmt"

	"github.com/nektos/act/pkg/model"
)

func planOrExplain(workflowDir, event, jobID string) (*model.Plan, error) {
	planner, err := model.NewWorkflowPlanner(workflowDir, true)
	if err != nil {
		return nil, err
	}
	var plan *model.Plan
	if jobID != "" {
		plan, err = planner.PlanJob(jobID)
	} else {
		plan, err = planner.PlanEvent(event)
	}
	if err != nil {
		return nil, err
	}
	if plan == nil || len(plan.Stages) == 0 {
		return nil, fmt.Errorf("no jobs match event %q / job %q; run 'act --list' to see valid IDs", event, jobID)
	}
	return plan, nil
}

Try / catch

if err := runExecute(cmd, args); err != nil {
    if strings.Contains(err.Error(), "Could not find any stages to run") {
        // discover valid jobs and retry with the first matching one
        return retryWithDiscoveredJobID()
    }
    return err
}

Prevention

Run 'act --list' before 'act -j <id>' to confirm the exact job ID.
Pass the right event ('act pull_request') when workflows only trigger on non-push events.
Run act from the repo root that contains .github/workflows/.

When it happens

Trigger: Running 'act -j <JobID>' where the ID is misspelled or the job's 'if:'/'needs:' excludes it for the event; running act with an event name (via -e/--event) that no workflow's 'on:' includes; workflows whose triggers (e.g. schedule, workflow_run) never match the default push event act simulates.

Common situations: Default push-event simulation vs workflows that only trigger on PR/schedule; renamed jobs after refactors; reusable-workflow-called jobs not visible to the planner; matrix jobs referenced by raw ID; wrong working directory so no .github/workflows files are found and zero jobs exist.

Related errors

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