wagoodman/dive · error

build option not supported for docker archive resolver

Error message

build option not supported for docker archive resolver

What it means

Returned by archiveResolver.Build (dive/image/docker/archive_resolver.go:37). A docker-archive resolver reads an already-saved tarball; it has no builder, so any Build() call fails with this fixed message. It implements the image.Resolver interface but only supports Fetch of a pre-existing archive.

Source

Thrown at dive/image/docker/archive_resolver.go:37

	return "docker-archive"
}

func (r *archiveResolver) Fetch(ctx context.Context, path string) (*image.Image, error) {
	reader, err := os.Open(path)
	if err != nil {
		return nil, err
	}
	defer reader.Close()

	img, err := NewImageArchive(reader)
	if err != nil {
		return nil, err
	}
	return img.ToImage(path)
}

func (r *archiveResolver) Build(ctx context.Context, args []string) (*image.Image, error) {
	return nil, fmt.Errorf("build option not supported for docker archive resolver")
}

func (r *archiveResolver) Extract(ctx context.Context, id string, l string, p string) error {
	return fmt.Errorf("not implemented")
}

View on GitHub (pinned to d6c691947f)

Solutions

1. Remove --build (and any -b/--build-arg style flags) when analyzing a saved tarball: dive docker-archive://image.tar or dive --source docker-archive image.tar
2. If you meant to build first, build with the engine resolver or plain 'docker build', then 'docker save' and analyze the tar
3. In library code, switch on the resolver type before calling Build, or check the configured source is engine-backed

Example fix

# before
dive --source docker-archive app.tar --build .

# after
dive --source docker-archive app.tar

// check the configured source before attempting a build
if src == dive.SourceDockerArchive {
    return fmt.Errorf("cannot --build with docker-archive source; pre-build and docker save instead")
}
img, err := resolver.Build(ctx, buildArgs)

img, err := resolver.Build(ctx, args)
if err != nil && strings.Contains(err.Error(), "build option not supported") {
    // fall back: build outside dive, analyze the produced image
    img, err = prebuiltImage(ctx) // your build-then-analyze path
}
if err != nil {
    return err
}

When it happens

Trigger: Combining an archive source with build semantics: 'dive --source docker-archive image.tar --build ...' or, as a library user, calling Build() on the resolver returned by NewResolverFromArchive() with any build arguments.

Common situations: CI pipelines that use one generic dive invocation with --build for engine sources and forget to drop the flag for archive analysis; Makefile targets that share BUILD_ARGS across docker and docker-archive invocations.

Related errors

• not implemented
• failed to set UI: %w
• cannot determine image provider for build: %w
• cannot build image: %w
• cannot determine image provider to fetch from: %w

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