{"record":{"id":"d38ec77ced9783f1","repo":"GoogleContainerTools/skaffold","slug":"transforming-image-for-debugging","errorCode":null,"errorMessage":"transforming image for debugging","messagePattern":"transforming image for debugging","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/skaffold/deploy/docker/deploy.go","lineNumber":239,"sourceCode":"func (d *Deployer) filterPortForwardingResources(imageName string) []*latest.PortForwardResource {\n\tfilteredPFResources := []*latest.PortForwardResource{}\n\tfor _, p := range d.resources {\n\t\tif strings.EqualFold(imageName, p.Name) {\n\t\t\tfilteredPFResources = append(filteredPFResources, p)\n\t\t}\n\t}\n\treturn filteredPFResources\n}\n\n// setupDebugging configures the provided artifact's image for debugging (if applicable).\n// The provided container configuration receives any relevant modifications (e.g. ENTRYPOINT, CMD),\n// and any init containers for populating the shared debug volume will be created.\n// A list of port bindings for the exposed debuggers is returned to be processed alongside other port\n// forwarding resources.\nfunc (d *Deployer) setupDebugging(ctx context.Context, out io.Writer, artifact graph.Artifact, containerCfg *container.Config) (network.PortMap, error) {\n\tinitContainers, err := d.debugger.TransformImage(ctx, artifact, containerCfg)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"transforming image for debugging\")\n\t}\n\n\t/*\n\t\tWhen images are transformed, a set of init containers is sometimes generated which\n\t\tprovide necessary debugging files into the application container. These files are\n\t\tshared via a volume created by the init container. We only need to create each init container\n\t\tonce, so we track the mounts on the DebugManager. These mounts are then added to the container\n\t\tconfiguration before creating the container in the daemon.\n\n\t\tNOTE: All tracked mounts (and created init containers) are assumed to be in the same Docker daemon,\n\t\tconfigured implicitly on the system. The tracking on the DebugManager will need to be updated to account\n\t\tfor the active daemon if this is ever extended to support multiple active Docker daemons.\n\t*/\n\tfor _, c := range initContainers {\n\t\tlabels := d.labeller.DebugLabels()\n\n\t\tif d.debugger.HasMount(c.Image) {\n\t\t\t// skip duplication of init containers","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/GoogleContainerTools/skaffold/blob/a1189de023efc32d4b8e11f395acc678aa555011/pkg/skaffold/deploy/docker/deploy.go#L221-L257","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped inner error to identify which image/config failed transformation","Verify the artifact built successfully and the image exists in the local daemon (docker images)","Run `skaffold debug -vdebug` to see the runtime-detection details for the artifact","Try a plain `skaffold run` (no debug) to confirm the image itself is deployable","Update Skaffold; unsupported runtimes/languages for debugging are fixed regularly"],"exampleFix":"// before\nskaffold debug --default-repo=gcr.io/me   // fails: transforming image for debugging\n// after\n# confirm image deploys without debug first\nskaffold run --default-repo=gcr.io/me\n# then check supported debug runtimes / update skaffold\nskaffold version && brew upgrade skaffold","handlingStrategy":"try-catch","validationCode":"if out, err := exec.Command(\"docker\", \"image\", \"inspect\", artifact.ImageName).CombinedOutput(); err != nil {\n  return fmt.Errorf(\"image %s not present in daemon before debug deploy: %s\", artifact.ImageName, out)\n}","typeGuard":"func hasContainerConfig(cfg *container.Config) bool { return cfg != nil && cfg.Image != \"\" }","tryCatchPattern":"if err := deployer.Deploy(ctx, out, artifacts); err != nil {\n  if strings.Contains(err.Error(), \"transforming image for debugging\") {\n    log.Printf(\"debug transform failed (inner: %v); falling back to plain run\", errors.Unwrap(err))\n    return plainRun(ctx, out, artifacts)\n  }\n  return err\n}","preventionTips":["Verify the artifact image builds and exists locally before `skaffold debug`","Keep skaffold up to date for current debug runtime support","Test with `skaffold run` first to isolate debug-specific failures","Use -vdebug to inspect runtime detection output"],"tags":["docker","deploy","debug","skaffold"],"backgroundTag":"debug-image-transform-failed","analyzedSha":"a1189de023efc32d4b8e11f395acc678aa555011","analyzedAt":"2026-09-05T12:09:27.064Z","contentChangedAt":"2026-09-05T12:09:27.064Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}