juanfont/headscale · error

inspecting image %s: %w

Error message

inspecting image %s: %w

What it means

Returned by `checkImageAvailableLocally` when `cli.ImageInspectWithRaw` fails with an error other than NotFound. NotFound itself is handled (returns available=false so a pull happens); any other daemon error — auth, API, daemon connection — gets wrapped with the image name for diagnosis.

Source

Thrown at cmd/hi/docker.go:520

	return nil, ErrNoDockerContext
}

// getDockerSocketPath returns the correct Docker socket path for the current context.
func getDockerSocketPath() string {
	// Always use the default socket path for mounting since Docker handles
	// the translation to the actual socket (e.g., colima socket) internally
	return "/var/run/docker.sock"
}

// checkImageAvailableLocally checks if the specified Docker image is available locally.
func checkImageAvailableLocally(ctx context.Context, cli *client.Client, imageName string) (bool, error) {
	_, _, err := cli.ImageInspectWithRaw(ctx, imageName) //nolint:staticcheck // SA1019: deprecated but functional
	if err != nil {
		if client.IsErrNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
			return false, nil
		}

		return false, fmt.Errorf("inspecting image %s: %w", imageName, err)
	}

	return true, nil
}

// ensureImageAvailable pulls imageName if missing, using Docker Hub
// credentials and retrying transient errors.
func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
	available, err := checkImageAvailableLocally(ctx, cli, imageName)
	if err != nil {
		return fmt.Errorf("checking local image availability: %w", err)
	}

	if available {
		if verbose {
			log.Printf("Image %s is available locally", imageName)
		}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify daemon access: `docker image inspect golang:<version>` as the same user.
2. Add yourself to the docker group if you get permission denied (`sudo usermod -aG docker $USER`, re-login).
3. Fix the daemon/context (`docker context use default`).
4. Check the image tag syntax in RunConfig.

Example fix

# before: permission denied on socket
go run ./cmd/hi run TestX  # inspecting image golang:...: ...permission denied

# after: grant access and re-login
sudo usermod -aG docker $USER  # then start a new shell
go run ./cmd/hi run TestX

// confirm socket access and image inspect works as this user
if err := exec.Command("docker", "image", "inspect", "golang:"+cfg.GoVersion).Run(); err != nil {
    // distinguish missing image (exit 1, 'No such image') from permission/daemon errors
    return fmt.Errorf("docker image inspect failed: %w", err)
}

if _, err := checkImageAvailableLocally(ctx, cli, image); err != nil {
    if !client.IsErrNotFound(err) {
        // daemon-level problem: check `docker info`, socket permissions, then retry
    }
}

When it happens

Trigger: Daemon unreachable during inspect; API version negotiation failure; permission denied against a restricted daemon socket; image reference syntactically invalid so the daemon errors rather than reporting NotFound.

Common situations: Docker daemon down or restarting; user not in the docker group (permission denied on the socket); remote context endpoint stale; malformed tag in config.GoVersion.

Related errors

• checking local image availability: %w
• creating directory failed with permission error
• cleaning stale test containers: %w
• pruning networks: %w
• removing test container: %w

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/00b4826856713fd1. Report an issue: GitHub.