GoogleContainerTools/skaffold · error

transforming image for debugging

Error message

transforming image for debugging

What it means

Skaffold's docker deployer wraps any failure from debugger.TransformImage, which rewrites the application container image to inject debugging support (debuggers, init containers, port bindings). If the image transformation fails — bad container config, unsupported image, or an internal debugger error — the deploy is aborted with this message wrapping the underlying cause.

Source

Thrown at pkg/skaffold/deploy/docker/deploy.go:239

func (d *Deployer) filterPortForwardingResources(imageName string) []*latest.PortForwardResource {
	filteredPFResources := []*latest.PortForwardResource{}
	for _, p := range d.resources {
		if strings.EqualFold(imageName, p.Name) {
			filteredPFResources = append(filteredPFResources, p)
		}
	}
	return filteredPFResources
}

// setupDebugging configures the provided artifact's image for debugging (if applicable).
// The provided container configuration receives any relevant modifications (e.g. ENTRYPOINT, CMD),
// and any init containers for populating the shared debug volume will be created.
// A list of port bindings for the exposed debuggers is returned to be processed alongside other port
// forwarding resources.
func (d *Deployer) setupDebugging(ctx context.Context, out io.Writer, artifact graph.Artifact, containerCfg *container.Config) (network.PortMap, error) {
	initContainers, err := d.debugger.TransformImage(ctx, artifact, containerCfg)
	if err != nil {
		return nil, errors.Wrap(err, "transforming image for debugging")
	}

	/*
		When images are transformed, a set of init containers is sometimes generated which
		provide necessary debugging files into the application container. These files are
		shared via a volume created by the init container. We only need to create each init container
		once, so we track the mounts on the DebugManager. These mounts are then added to the container
		configuration before creating the container in the daemon.

		NOTE: All tracked mounts (and created init containers) are assumed to be in the same Docker daemon,
		configured implicitly on the system. The tracking on the DebugManager will need to be updated to account
		for the active daemon if this is ever extended to support multiple active Docker daemons.
	*/
	for _, c := range initContainers {
		labels := d.labeller.DebugLabels()

		if d.debugger.HasMount(c.Image) {
			// skip duplication of init containers

View on GitHub (pinned to a1189de023)

Solutions

1. Read the wrapped inner error to identify which image/config failed transformation
2. Verify the artifact built successfully and the image exists in the local daemon (docker images)
3. Run `skaffold debug -vdebug` to see the runtime-detection details for the artifact
4. Try a plain `skaffold run` (no debug) to confirm the image itself is deployable
5. Update Skaffold; unsupported runtimes/languages for debugging are fixed regularly

Example fix

// before
skaffold debug --default-repo=gcr.io/me   // fails: transforming image for debugging
// after
# confirm image deploys without debug first
skaffold run --default-repo=gcr.io/me
# then check supported debug runtimes / update skaffold
skaffold version && brew upgrade skaffold

if out, err := exec.Command("docker", "image", "inspect", artifact.ImageName).CombinedOutput(); err != nil {
  return fmt.Errorf("image %s not present in daemon before debug deploy: %s", artifact.ImageName, out)
}

func hasContainerConfig(cfg *container.Config) bool { return cfg != nil && cfg.Image != "" }

if err := deployer.Deploy(ctx, out, artifacts); err != nil {
  if strings.Contains(err.Error(), "transforming image for debugging") {
    log.Printf("debug transform failed (inner: %v); falling back to plain run", errors.Unwrap(err))
    return plainRun(ctx, out, artifacts)
  }
  return err
}

When it happens

Trigger: setupDebugging (called from Deployer.Deploy) invokes d.debugger.TransformImage(ctx, artifact, containerCfg) and that call returns an error, e.g. because the artifact image config cannot be transformed for the detected runtime or the daemon rejected the operation.

Common situations: Deploying with `skaffold debug` to a local Docker daemon with an image whose runtime could not be detected; malformed containerCfg (missing/invalid entrypoint or env); the debug support tooling failing to parse the built image.

Related errors

• setting up debugger
• creating container in local docker
• %q running container image %q errored during run with status
• docker deployment not supported alongside cluster deployment
• INIT_DOCKER_NETWORK_CONTAINER_DOES_NOT_EXIST

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/d38ec77ced9783f1. Report an issue: GitHub.