What causes "failed to list containers: %w" in nektos/act?

docker ps -a to confirm the daemon answers and you have permission

failed to list containers: %w

Error message

failed to list containers: %w

What it means

containerReference.find looks for an existing container with the job's name via ContainerList(All: true) so act can reuse it. If the Docker daemon rejects the list call, 'failed to list containers' wraps the API error.

Source

Thrown at pkg/container/docker_run.go:316

			cr.cli = nil
			if err != nil {
				return fmt.Errorf("failed to close client: %w", err)
			}
		}
		return nil
	}
}

func (cr *containerReference) find() common.Executor {
	return func(ctx context.Context) error {
		if cr.id != "" {
			return nil
		}
		result, err := cr.cli.ContainerList(ctx, client.ContainerListOptions{
			All: true,
		})
		if err != nil {
			return fmt.Errorf("failed to list containers: %w", err)
		}

		for _, c := range result.Items {
			for _, name := range c.Names {
				if name[1:] == cr.input.Name {
					cr.id = c.ID
					return nil
				}
			}
		}

		cr.id = ""
		return nil
	}
}

func (cr *containerReference) remove() common.Executor {
	return func(ctx context.Context) error {

View on GitHub (pinned to 4f41128141)

Solutions

docker ps -a to confirm the daemon answers and you have permission
Add yourself to the docker group or fix socket permissions for rootless setups
Restart the Docker daemon if it is wedged; prune stale containers (docker container prune)
Re-run the workflow after the daemon is healthy

Defensive patterns

Strategy: retry

Validate before calling

# shell pre-flight
docker ps >/dev/null || { echo "daemon not answering" >&2; exit 1; }
[ -S /var/run/docker.sock ] && [ -r /var/run/docker.sock ] || echo "check socket perms/group"

Try / catch

// Go: retry list once — transient daemon restarts are common
var items []container.Summary
var err error
for i := 0; i < 2; i++ {
    res, e := cli.ContainerList(ctx, client.ContainerListOptions{All: true})
    if e == nil { items = res.Items; break }
    err = e
    time.Sleep(time.Second)
}

Prevention

Run docker ps before long jobs to confirm availability
For rootless/socket setups, ensure the invoking user has access
Prune leftover act- containers between runs

When it happens

Trigger: Docker API ContainerList failing: daemon down or restarting, permission denied (rootless socket vs root daemon, user not in docker group), or a proxy/remote endpoint that breaks the API mid-run.

Common situations: Docker service restarting during a long act run, disk pressure causing the daemon to be unresponsive, CI environments where the docker socket is mounted read-only, or interrupted prior runs leaving act's name-matching unable to proceed.

Related errors

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