GoogleContainerTools/skaffold · error · DebugHelperRetrieveErr

retrieving debug helpers registry: %w

Error message

retrieving debug helpers registry: %w

What it means

When container debugging is enabled (`ContainerDebugging()`), the Docker deployer needs a registry of debug helper images, read from the user's skaffold global config via `config.GetDebugHelpersRegistry`. If reading that configuration fails, NewDeployer wraps the error with DebugHelperRetrieveErr.

Source

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

}

func NewDeployer(ctx context.Context, cfg dockerutil.Config, labeller *label.DefaultLabeller, d *latest.DockerDeploy, resources []*latest.PortForwardResource, configName string) (*Deployer, error) {
	client, err := dockerutil.NewAPIClient(ctx, cfg)
	if err != nil {
		return nil, err
	}

	tracker := tracker.NewContainerTracker()
	l, err := logger.NewLogger(ctx, tracker, cfg, true)
	if err != nil {
		return nil, err
	}

	var dbg *debugger.DebugManager
	if cfg.ContainerDebugging() {
		debugHelpersRegistry, err := config.GetDebugHelpersRegistry(cfg.GlobalConfig())
		if err != nil {
			return nil, deployerr.DebugHelperRetrieveErr(fmt.Errorf("retrieving debug helpers registry: %w", err))
		}
		dbg = debugger.NewDebugManager(cfg.GetInsecureRegistries(), debugHelpersRegistry)
	}

	return &Deployer{
		configName:         configName,
		cfg:                d,
		client:             client,
		network:            fmt.Sprintf("skaffold-network-%s", labeller.GetRunID()),
		networkDeployed:    false,
		resources:          resources,
		globalConfig:       cfg.GlobalConfig(),
		insecureRegistries: cfg.GetInsecureRegistries(),
		tracker:            tracker,
		portManager:        dockerport.NewPortManager(), // fulfills Accessor interface
		debugger:           dbg,
		logger:             l,
		monitor:            &status.NoopMonitor{},

View on GitHub (pinned to a1189de023)

Solutions

1. Inspect and repair or delete ~/.skaffold/config (skaffold recreates it on next run)
2. Set the debug helpers registry explicitly, e.g. `skaffold config set debug-helpers-registry <registry>`, ensuring the registry value is valid
3. Run with --container-debugging disabled if debugging helpers are not needed

Example fix

// before (corrupted global config)
{ "debug-helpers-registry": "" ,,

// after (reset and set properly)
rm ~/.skaffold/config
skaffold config set debug-helpers-registry gcr.io/my-project

if _, err := os.Stat(filepath.Join(home, ".skaffold", "config")); err == nil {
    if data, err := os.ReadFile(filepath.Join(home, ".skaffold", "config")); err == nil {
        var m map[string]interface{}
        if json.Unmarshal(data, &m) != nil {
            // corrupted config; back it up and remove before running skaffold
        }
    }
}

if err := runSkaffoldWithDebugging(); err != nil {
    var dbgErr *skaffold.Error
    if errors.As(err, &dbgErr) && dbgErr.ErrCode == proto.StatusCode_DEPLOY_DEBUG_HELPER_RETRIEVE_ERR {
        // reset ~/.skaffold/config and retry
        os.Remove(filepath.Join(home, ".skaffold", "config"))
    }
}

When it happens

Trigger: Running `skaffold dev/run --container-debugging` (or debugging via IDE integration) while the global config (~/.skaffold/config) is unreadable, malformed, or the debug-helpers registry field cannot be resolved.

Common situations: Corrupted or hand-edited ~/.skaffold/config; permissions issues on the config file; invalid registry value that fails validation.

Related errors

• retrieving insecure registries: %w
• unable to evaluate cli flags: %w
• normalizing dockerfile path: %w
• creating actiosn runner: %w
• setting up debugger

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