docker/cli · error

error registering pruner: prune function is nil for %s

Error message

error registering pruner: prune function is nil for %s

What it means

Returned by pruner.Register when a nil PruneFunc is passed for the given content type. Since registered pruners are invoked directly by `docker system prune`, a nil function would panic at prune time, so registration rejects it up front.

Source

Thrown at cli/command/system/pruner/pruner.go:103

// Register registers a [PruneFunc] under the given name to be included in
// "docker system prune". It is designed to be called in an init function
// and is not safe for concurrent use.
//
// For example:
//
//	 func init() {
//		// Register the prune command to run as part of "docker system prune".
//		if err := prune.Register(prune.TypeImage, prunerFn); err != nil {
//			panic(err)
//		}
//	}
func Register(name ContentType, pruneFunc PruneFunc) error {
	if name == "" {
		return errors.New("error registering pruner: invalid prune type: cannot be empty")
	}
	if pruneFunc == nil {
		return errors.New("error registering pruner: prune function is nil for " + string(name))
	}
	if registered == nil {
		registered = make(map[ContentType]PruneFunc)
	}
	if _, exists := registered[name]; exists {
		return fmt.Errorf("error registering pruner: content-type %s is already registered", name)
	}
	registered[name] = pruneFunc
	return nil
}

// List iterates over all registered pruners, starting with known pruners
// in their predefined order, followed by any others (sorted alphabetically).
func List() iter.Seq2[ContentType, PruneFunc] {
	all := maps.Clone(registered)
	ordered := make([]ContentType, 0, len(all))
	for _, ct := range pruneOrder {
		if _, ok := all[ct]; ok {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Pass a concrete, non-nil PruneFunc at registration time.
2. If the function is assigned elsewhere, restructure so Register is called after assignment (or register a closure that resolves the implementation at call time).

Example fix

// before
var pruneFn pruner.PruneFunc // nil at init time
func init() { _ = pruner.Register(pruner.TypeImage, pruneFn) }
// after
func init() {
    _ = pruner.Register(pruner.TypeImage, func(ctx context.Context, cli command.Cli, opts pruner.Options) (uint64, string, error) {
        return runImagePrune(ctx, cli, opts)
    })
}

When it happens

Trigger: Calling pruner.Register(name, nil) from an init() function — e.g. passing a function variable that hasn't been assigned yet due to package initialization order, at cli/command/system/pruner/pruner.go:103.

Common situations: Fork/extension authors passing a nil function pointer; init-order bugs where the PruneFunc variable is populated after the Register call runs. Not reachable through normal docker CLI usage — it is a defensive check against programming errors.

Related errors

• error registering pruner: invalid prune type: cannot be empt
• failed to parse hook template
• unexpected hook response type:
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/26b57b7c80f0e056.json. Report an issue: GitHub.