wagoodman/dive · error

unable to determine image resolver

Error message

unable to determine image resolver

What it means

Returned by dive.GetImageResolver (dive/get_image_resolver.go:72) when the ImageSource value falls outside the handled set {SourceDockerEngine, SourcePodmanEngine, SourceDockerArchive}. The zero value SourceUnknown (as well as any out-of-range integer) hits the default branch, so this error really means 'the image source was never recognized'.

Source

Thrown at dive/get_image_resolver.go:72

	case SourceDockerArchive.String():
		return SourceDockerArchive, imageSource
	case "docker-tar":
		return SourceDockerArchive, imageSource
	}
	return SourceUnknown, ""
}

func GetImageResolver(r ImageSource) (image.Resolver, error) {
	switch r {
	case SourceDockerEngine:
		return docker.NewResolverFromEngine(), nil
	case SourcePodmanEngine:
		return podman.NewResolverFromEngine(), nil
	case SourceDockerArchive:
		return docker.NewResolverFromArchive(), nil
	}

	return nil, fmt.Errorf("unable to determine image resolver")
}

View on GitHub (pinned to d6c691947f)

Solutions

1. Pass an explicit source: dive docker://<image>, dive podman://<image>, or dive --source docker-archive docker-image.tar
2. Fix the flag spelling - only lowercase 'docker', 'podman', 'docker-archive' (alias 'docker-tar') are accepted
3. Library callers: validate the source before resolving - reject ImageSource values not in ImageSources or equal to SourceUnknown
4. Ensure the image argument includes its scheme prefix when you rely on DeriveImageSource

Example fix

// before
resolver, err := dive.GetImageResolver(src) // src == dive.SourceUnknown

// after
if src == dive.SourceUnknown {
    return fmt.Errorf("unsupported image source (have you tried --source docker|podman|docker-archive?)")
}
resolver, err := dive.GetImageResolver(src)

// validate before resolving
if src == dive.SourceUnknown {
    src = dive.ParseImageSource(flagSource) // "docker" | "podman" | "docker-archive" | "docker-tar"
}
if src == dive.SourceUnknown {
    return fmt.Errorf("unsupported source %q (want docker|podman|docker-archive)", flagSource)
}
resolver, err := dive.GetImageResolver(src)

resolver, err := dive.GetImageResolver(src)
if err != nil {
    if strings.Contains(err.Error(), "unable to determine image resolver") {
        // guide the user to a valid source rather than failing opaquely
        return fmt.Errorf("source not recognized; use --source docker|podman|docker-archive or a scheme:// prefix")
    }
    return err
}

When it happens

Trigger: ParseImageSource returning SourceUnknown because the --source/-s flag value is not exactly 'docker', 'podman', 'docker-archive' (or legacy 'docker-tar'); DeriveImageSource returning SourceUnknown because the image argument has no 'scheme://' prefix and no --source flag was given; calling GetImageResolver(SourceUnknown) or GetImageResolver(42) directly from library code.

Common situations: Running 'dive alpine:3' without --source while DOCKER_HOST is unset so auto-detection has nothing to probe; typos like --source dockerEngine or --source docker_engine; new/renamed sources after a dive upgrade; library users passing an uninitialized ImageSource variable.

Related errors

• unable to determine image source from %q: %v
• failed to unmarshal CI config file %s: %w
• cannot determine image provider for build: %w
• invalid %s config value, given %q: %v
• %s config value is outside allowed range (0-1), given '%f'

AI-assisted analysis of wagoodman/dive@d6c691947f (2026-08-15). Data as JSON: /api/errors/921622982b5f7b88. Report an issue: GitHub.