What causes "failed to connect to docker daemon: %w" in nektos/act?

Inspect DOCKER_HOST: valid forms are unix:///var/run/docker.sock, tcp://host:port, ssh://user@host, npipe://... (Windows)

nektos/act · critical

failed to connect to docker daemon: %w

Error message

failed to connect to docker daemon: %w

What it means

GetDockerClient builds a Docker API client either from a ssh:// DOCKER_HOST (via connhelper) or from the environment (client.FromEnv). If client.New fails — malformed host URL, unsupported scheme, bad TLS config — the wrapped error 'failed to connect to docker daemon' is returned. Note it fires on client construction, not on an actual ping of the daemon.

Source

Thrown at pkg/container/docker_run.go:236

func GetDockerClient(_ context.Context) (cli client.APIClient, err error) {
	dockerHost := os.Getenv("DOCKER_HOST")

	if strings.HasPrefix(dockerHost, "ssh://") {
		var helper *connhelper.ConnectionHelper

		helper, err = connhelper.GetConnectionHelper(dockerHost)
		if err != nil {
			return nil, err
		}
		cli, err = client.New(
			client.WithHost(helper.Host),
			client.WithDialContext(helper.Dialer),
		)
	} else {
		cli, err = client.New(client.FromEnv)
	}
	if err != nil {
		return nil, fmt.Errorf("failed to connect to docker daemon: %w", err)
	}

	return cli, nil
}

func GetHostInfo(ctx context.Context) (info system.Info, err error) {
	var cli client.APIClient
	cli, err = GetDockerClient(ctx)
	if err != nil {
		return info, err
	}
	defer cli.Close()

	result, err := cli.Info(ctx, client.InfoOptions{})
	if err != nil {
		return info, err
	}

View on GitHub (pinned to 4f41128141)

Solutions

Inspect DOCKER_HOST: valid forms are unix:///var/run/docker.sock, tcp://host:port, ssh://user@host, npipe://... (Windows)
docker context show / docker context ls to find the intended endpoint and align DOCKER_HOST
Unset DOCKER_HOST to use the local socket: env -u DOCKER_HOST act ...
For TLS endpoints, verify DOCKER_CERT_PATH contains ca.pem/cert.pem/key.pem matching DOCKER_TLS_VERIFY=1

Example fix

# before
export DOCKER_HOST=tcp://localhost  # missing port / wrong scheme

# after
export DOCKER_HOST=unix:///var/run/docker.sock

Defensive patterns

Strategy: try-catch

Validate before calling

# shell: validate the endpoint before running act
case "$DOCKER_HOST" in
  unix:///*|tcp://*:*|ssh://*|npipe://*|"") : ;;
  *) echo "bad DOCKER_HOST: $DOCKER_HOST" >&2; exit 1 ;;
esac
docker version >/dev/null

Try / catch

// Go: construct the client, then verify with a cheap call
cli, err := container.GetDockerClient(ctx)
if err != nil {
    return fmt.Errorf("docker client setup failed (check DOCKER_HOST=%q): %w", os.Getenv("DOCKER_HOST"), err)
}
defer cli.Close()
if _, err := cli.Info(ctx, client.InfoOptions{}); err != nil { return err }

Prevention

Standardize DOCKER_HOST via docker context instead of ad-hoc exports
In CI, assert docker version as the first step before act
Keep TLS env vars (DOCKER_TLS_VERIFY, DOCKER_CERT_PATH) paired and consistent

When it happens

Trigger: DOCKER_HOST set to an invalid or unsupported value (e.g. tcp://[::1, unknown scheme), DOCKER_TLS_VERIFY/DOCKER_CERT_PATH misconfigured, or ssh:// host where connhelper setup succeeded but client options are rejected.

Common situations: Broken DOCKER_HOST after switching between docker contexts, stale docker-machine/remote settings, missing client certificates, or a typo'd unix socket path. act fails at startup before any container work.

Related errors

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