GoogleContainerTools/skaffold · error

setting up debugger

Error message

setting up debugger

What it means

The docker Deployer's deploy step, when a debugger is configured (debug helper), calls setupDebugging to compute debug port bindings and support mounts for the artifact container. Any failure inside that setup is wrapped as "setting up debugger". Without it, the container would run but be un-debuggable, so deploy aborts.

Source

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

	}

	containerCfg, err := d.containerConfigFromImage(ctx, artifact.Tag)
	if err != nil {
		return err
	}

	containerName := d.getContainerName(ctx, artifact.ImageName)
	opts := dockerutil.ContainerCreateOpts{
		Name:            containerName,
		Network:         d.network,
		ContainerConfig: containerCfg,
	}

	var debugBindings network.PortMap
	if d.debugger != nil {
		debugBindings, err = d.setupDebugging(ctx, out, artifact, containerCfg)
		if err != nil {
			return errors.Wrap(err, "setting up debugger")
		}

		// mount all debug support container volumes into the application container
		var mounts []mount.Mount
		for _, m := range d.debugger.SupportMounts() {
			mounts = append(mounts, m)
		}
		opts.Mounts = mounts
	}

	// Filter for the port resource for the given artifact.ImageName
	filteredPFResources := d.filterPortForwardingResources(artifact.ImageName)

	bindings, err := d.portManager.AllocatePorts(artifact.ImageName, filteredPFResources, containerCfg, debugBindings)
	if err != nil {
		return err
	}
	opts.Bindings = bindings

View on GitHub (pinned to a1189de023)

Solutions

1. Read the unwrapped inner error — it identifies whether image inspection, runtime detection, or port setup failed.
2. Rebuild the image so it contains a supported runtime and debug support (e.g. correct Go/JVM/Node/Python version).
3. Verify the artifact type/language is supported by skaffold debug for docker deploys.
4. Free or remap conflicting debug ports on the host.
5. If debugging is not needed, deploy without the debug profile enabled.

Example fix

// before
skaffold dev --profile debug
// after
# ensure the image is rebuilt with debug support, then
skaffold build && skaffold dev --profile debug

// before enabling debug, confirm runtime support in the image
inspect, err := cli.ImageInspect(ctx, image)
if err != nil { return fmt.Errorf("cannot inspect %s: %w", image, err) }

// Go
if _, err := d.Deploy(ctx, out, artifacts); err != nil {
    if strings.Contains(err.Error(), "setting up debugger") {
        log.Print("debug setup failed; retrying deploy without debug profile")
    }
}

When it happens

Trigger: Calling Deploy on a docker deployer with debugger != nil when setupDebugging fails: the artifact image lacks the runtime the debugger expects, the debug configuration for the language is unsupported/invalid, image inspection fails, or port binding computation errors.

Common situations: `skaffold debug` (or a profile with debug: true) against an image built without the required tooling; unsupported language/runtime version inside the image; image pull/inspect failure; debug ports already occupied on the host.

Related errors

• creating container in local docker
• transforming image for debugging
• %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/65f8bb7139bbf6be. Report an issue: GitHub.