wagoodman/dive · error

unable to determine image source from %q: %v

Error message

unable to determine image source from %q: %v

What it means

Thrown during options post-processing when dive cannot map the user-supplied image argument (and the configured container engine) to any known image source. dive.DeriveImageSource() on the image string returned SourceUnknown, and the fallback dive.ParseImageSource(engine) for the configured engine also returned SourceUnknown, so there is no way to fetch the image.

Source

Thrown at cmd/dive/cli/internal/options/analysis.go:61

		fmt.Sprintf("The container engine to fetch the image from. Allowed values: %s", strings.Join(c.AvailableContainerEngines, ", ")))

	flags.BoolVarP(&c.IgnoreErrors, "ignore-errors", "i", "ignore image parsing errors and run the analysis anyway")
}

func (c *Analysis) PostLoad() error {
	validEngines := strset.New(c.AvailableContainerEngines...)
	if !validEngines.Has(c.ContainerEngine) {
		log.Warnf("invalid container engine: %s (valid options: %s), using default %q", c.ContainerEngine, strings.Join(c.AvailableContainerEngines, ", "), defaultContainerEngine)
		c.ContainerEngine = "docker"
	}

	if c.Image != "" {
		sourceType, imageStr := dive.DeriveImageSource(c.Image)

		if sourceType == dive.SourceUnknown {
			sourceType = dive.ParseImageSource(c.ContainerEngine)
			if sourceType == dive.SourceUnknown {
				return fmt.Errorf("unable to determine image source from %q: %v\n", c.Image, c.ContainerEngine)
			}

			// use exactly what the user provided
			imageStr = c.Image
		}

		c.Image = imageStr
		c.Source = sourceType
	} else {
		c.Source = dive.ParseImageSource(c.ContainerEngine)
	}

	return nil
}

View on GitHub (pinned to d6c691947f)

Solutions

1. Re-check the image argument spelling and scheme prefix; prefer plain 'docker.io/library/ubuntu:latest' style references or 'docker-archive://path/to.tar'.
2. Explicitly pass a supported --engine (docker, podman) matching where the image actually lives.
3. If using an engine alias, confirm it exactly matches one of AvailableContainerEngines, since unknown engines silently fall back to docker.
4. Upgrade dive if you rely on a newer source-scheme (e.g. OCI layout) supported only in later versions.

Example fix

# before
dive dockerarchive:///tmp/img.tar   # scheme typo -> unable to determine image source

# after
dive docker-archive:///tmp/img.tar

# validate before running dive
[ -n "$IMAGE" ] || { echo "image required"; exit 1; }
case "$IMAGE" in
  docker-archive://*|*.tar) ENGINE_FLAGS="";;
  *) ENGINE_FLAGS="--engine docker";;
esac
dive $ENGINE_FLAGS "$IMAGE"

When it happens

Trigger: Passing an image string that matches no supported source scheme (not a docker-archive: OCI tar, podman remote syntax, etc.) while the --engine flag is also set to an unrecognized value. Note the engine is validated against AvailableContainerEngines above and falls back to 'docker', so in practice this fires when the image string itself is malformed for the resolved engine.

Common situations: Typos in the image name or scheme prefix (e.g. dockerarchive:// instead of docker-archive://); using a source format only supported by a different engine version; passing a custom engine name not in AvailableContainerEngines combined with an ambiguous image string.

Related errors

• failed to unmarshal CI config file %s: %w
• unable to determine image resolver
• cannot export analysis: %w
• directory for JSON export does not exist: %s
• file tree has path errors (use '--ignore-errors' to attempt

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