What causes "executor plugin metadata name is mandatory" in argoproj/argo-workflows?

Set metadata.name on the ExecutorPlugin resource to a non-empty value

executor plugin metadata name is mandatory

Error message

executor plugin metadata name is mandatory

What it means

When Argo converts an ExecutorPlugin spec into a sidecar container to inject into workflow pods, the plugin's metadata.name is required because it identifies the plugin. This error is returned from the conversion function when plugin.Name is empty.

Source

Thrown at pkg/apis/workflow/v1alpha1/workflow_types.go:564

	return &wfs.ArtifactGC.ArtifactGC
}

func (wfs WorkflowSpec) GetTTLStrategy() *TTLStrategy {
	return wfs.TTLStrategy
}

// AsExecutorPluginSpec maps proto models to v4/pkg/plugins/spec models.
func (wfs WorkflowSpec) AsExecutorPluginSpec() ([]execplugin.Plugin, error) {
	plugins := make([]execplugin.Plugin, 0, len(wfs.ExecutorPlugins))
	for _, plugin := range wfs.ExecutorPlugins {
		sidecar := execplugin.Sidecar{
			AutomountServiceAccountToken: plugin.Spec.Sidecar.AutomountServiceAccountToken,
			Container:                    plugin.Spec.Sidecar.Container,
		}

		if plugin.Name == "" {
			return nil, fmt.Errorf("executor plugin metadata name is mandatory")
		}
		err := sidecar.Validate()
		if err != nil {
			return nil, err
		}

		spec := execplugin.PluginSpec{
			Sidecar: sidecar,
		}
		plugins = append(plugins, execplugin.Plugin{
			ObjectMeta: plugin.ObjectMeta,
			Spec:       spec,
		})
	}
	return plugins, nil
}

// GetSemaphoreKeys will return list of semaphore configmap keys which are configured in the workflow

View on GitHub (pinned to 35bff19146)

Solutions

Set metadata.name on the ExecutorPlugin resource to a non-empty value
Ensure the YAML indentation places `name` under `metadata:`
Validate with `kubectl apply --dry-run=server` before submitting workflows

Example fix

# before
apiVersion: argoproj.io/v1alpha1
kind: ExecutorPlugin
spec: ...
# after
apiVersion: argoproj.io/v1alpha1
kind: ExecutorPlugin
metadata:
  name: my-plugin
spec: ...

Defensive patterns

Strategy: validation

Validate before calling

if plugin.ObjectMeta.Name == "" {
    return errors.New("executor plugin requires metadata.name")
}

Try / catch

sidecar, err := execplugin.GetContainer(plugin)
if err != nil {
    return fmt.Errorf("invalid ExecutorPlugin %q: %w", plugin.Name, err)
}

Prevention

Validate ExecutorPlugin manifests with kubectl dry-run before apply
Use kubebuilder/CRD validation markers requiring metadata.name
Lint plugin YAML in CI

When it happens

Trigger: Applying an ExecutorPlugin custom resource (or loading one in code) whose `metadata.name` field is missing or empty, which then flows into the plugin-to-sidecar conversion.

Common situations: YAML with metadata omitted or indented wrong so name is not parsed; programmatically constructing an ExecutorPlugin struct without setting Name.

Related errors

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/7069ae707cdce122. Report an issue: GitHub.