docker/cli · error

error registering pruner: invalid prune type: cannot be empt

Error message

error registering pruner: invalid prune type: cannot be empty

What it means

Returned by pruner.Register when a pruner is registered with an empty ContentType name. Register is called from init() functions to add content types (images, containers, networks, volumes, build-cache) to `docker system prune`; an empty name would make the pruner unaddressable, so registration fails fast.

Source

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

// registered holds a map of PruneFunc functions registered through [Register].
// It is considered immutable after startup.
var registered map[ContentType]PruneFunc

// 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)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Pass a non-empty ContentType when registering: define a constant like `const TypeFoo pruner.ContentType = "foo"` and use it.
2. Audit init() functions in your fork/plugin for Register calls with uninitialized ContentType values.

Example fix

// before
func init() {
    if err := pruner.Register("", pruneFn); err != nil { panic(err) }
}
// after
const TypeWidget pruner.ContentType = "widget"
func init() {
    if err := pruner.Register(TypeWidget, pruneFn); err != nil { panic(err) }
}

When it happens

Trigger: Calling pruner.Register("", fn) — i.e. code (typically an init() in a CLI package or a fork/extension of docker/cli) passing an empty ContentType constant at cli/command/system/pruner/pruner.go:100.

Common situations: Developers extending docker/cli with a custom pruner and forgetting to define the ContentType constant; refactors that leave a ContentType variable zero-valued. End users of the stock docker CLI should never see this — it indicates a programming error, and callers typically panic on it in init().

Related errors

• error registering pruner: prune function is nil for %s
• 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/7957d6ffb23d498d.json. Report an issue: GitHub.