unable to determine if image already exists for image '%s' (

Error message

unable to determine if image already exists for image '%s' (%s): %w

What it means

NewDockerPullExecutor first checks whether the image already exists locally (unless --pull or ForcePull is set) to skip unnecessary pulls. ImageExistsLocally needs a working Docker client and a parseable image reference; if that check itself fails, the pull is aborted with this wrapped error naming the image and platform.

Source

Thrown at pkg/container/docker_pull.go:35

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

// NewDockerPullExecutor function to create a run executor for the container
func NewDockerPullExecutor(input NewDockerPullExecutorInput) common.Executor {
	return func(ctx context.Context) error {
		logger := common.Logger(ctx)
		logger.Debugf("%sdocker pull %v", logPrefix, input.Image)

		if common.Dryrun(ctx) {
			return nil
		}

		pull := input.ForcePull
		if !pull {
			imageExists, err := ImageExistsLocally(ctx, input.Image, input.Platform)
			logger.Debugf("Image exists? %v", imageExists)
			if err != nil {
				return fmt.Errorf("unable to determine if image already exists for image '%s' (%s): %w", input.Image, input.Platform, err)
			}

			if !imageExists {
				pull = true
			}
		}

		if !pull {
			return nil
		}

		imageRef := cleanImage(ctx, input.Image)
		logger.Debugf("pulling image '%v' (%s)", imageRef, input.Platform)

		cli, err := GetDockerClient(ctx)
		if err != nil {
			return err
		}

View on GitHub (pinned to 4f41128141)

Solutions

Check the wrapped error: connection problems point to the daemon, parse problems point to the image name
docker ps to verify the daemon is up; restart Docker if needed
Fix or verify the image reference (docker pull <image> manually)
As a workaround, --pull forces the pull path, but fix the underlying daemon/reference issue first

Example fix

jobs:
  test:
    container:
      # before: image: node:20 11  (typo -> invalid reference)
      image: node:20

Defensive patterns

Strategy: retry

Validate before calling

# shell: pre-flight before act
image=$(yq '.jobs.*.container.image | select(. != null)' .github/workflows/ci.yml | head -1)
docker pull "$image" # validates reference AND daemon reachability

Try / catch

// Go: retry once after a short delay, then surface the wrapped cause
var err error
for i := 0; i < 2; i++ {
    if err = NewDockerPullExecutor(input)(ctx); err == nil { break }
    time.Sleep(2 * time.Second)
}
if err != nil { return fmt.Errorf("pull failed: %w", err) }

Prevention

Keep the Docker daemon healthy; docker ps as a pre-flight in CI
Use fully-qualified, valid image references
Watch the wrapped error: connection vs. reference tells you the fix

When it happens

Trigger: ImageExistsLocally fails: Docker daemon unreachable or erroring on ImageList, or the image reference string is invalid so normalization fails. Happens only when ForcePull is false and dry-run is off.

Common situations: Docker daemon stopped/crashed mid-run, DOCKER_HOST pointing at a dead socket, docker desktop restarting, or a typo in the job's container image / uses image string that is not a valid reference.

Related errors

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