What causes "must specify plugin allocation ID to deregister" in hashicorp/nomad?

Pass the alloc.ID of the allocation that registered the plugin

must specify plugin allocation ID to deregister

Error message

must specify plugin allocation ID to deregister

What it means

DeregisterPlugin tracks which allocation (allocID) holds the plugin registration so usage can be reference-counted. An empty allocID prevents the registry from updating the per-allocation registration correctly, so it is rejected.

Source

Thrown at client/dynamicplugins/registry.go:255

	return broadcaster
}

func (d *dynamicRegistry) DeregisterPlugin(ptype, name, allocID string) error {
	d.pluginsLock.Lock()
	defer d.pluginsLock.Unlock()

	if ptype == "" {
		// This error shouldn't make it to a production cluster and is to aid
		// developers during the development of new plugin types.
		return errors.New("must specify plugin type to deregister")
	}
	if name == "" {
		// This error shouldn't make it to a production cluster and is to aid
		// developers during the development of new plugin types.
		return errors.New("must specify plugin name to deregister")
	}
	if allocID == "" {
		return errors.New("must specify plugin allocation ID to deregister")
	}

	pmap, ok := d.plugins[ptype]
	if !ok {
		// If this occurs there's a bug in the registration handler.
		return fmt.Errorf("no plugins registered for type: %s", ptype)
	}

	infos, ok := pmap[name]
	if !ok {
		// plugin already deregistered, don't send events or try re-deleting.
		return nil
	}

	var info *PluginInfo
	for e := infos.Front(); e != nil; e = e.Next() {
		info = e.Value.(*PluginInfo)
		if info.AllocID == allocID {

View on GitHub (pinned to 482b49bf1a)

Solutions

Pass the alloc.ID of the allocation that registered the plugin
Validate allocID is non-empty before calling DeregisterPlugin
Check that the deregistering code path has access to the alloc state and is not invoked with a nil/partial alloc

Example fix

// before
err := registry.DeregisterPlugin(ptype, name, "")
// after
if allocID == "" {
    return fmt.Errorf("cannot deregister plugin %s/%s: empty alloc ID", ptype, name)
}
err := registry.DeregisterPlugin(ptype, name, allocID)

Defensive patterns

Strategy: validation

Validate before calling

if allocID == "" {
    return fmt.Errorf("deregister: alloc ID is required")
}
err := registry.DeregisterPlugin(ptype, name, allocID)

Type guard

func canDeregister(ptype, name, allocID string) bool {
    return ptype != "" && name != "" && allocID != ""
}

Try / catch

err := registry.DeregisterPlugin(ptype, name, allocID)
if err != nil {
    if strings.Contains(err.Error(), "must specify plugin allocation ID") {
        return fmt.Errorf("alloc %q deregistration of plugin %s/%s missing alloc ID: %w", allocID, ptype, name, err)
    }
    return err
}

Prevention

Ensure deregistration is only invoked with a valid alloc state (non-empty alloc.ID)
Avoid invoking plugin deregistration outside the alloc lifecycle helpers
Log allocID at deregistration call sites to catch empty values early

When it happens

Trigger: Calling Registry.DeregisterPlugin(ptype, name, "") with an empty allocation ID, typically in client alloc teardown when the allocation ID was not propagated to the plugin cleanup code.

Common situations: Running plugin deregistration outside a normal alloc lifecycle (manual cleanup, tests), or alloc restore paths where the allocID field is empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/5629dde9772e8254. Report an issue: GitHub.