argoproj/argo-workflows · error

workflow-level executor plugins are disabled in the controll

Error message

workflow-level executor plugins are disabled in the controller. To enable them, set the environment variable ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true

What it means

Workflow-level executor plugins (defined in workflow.spec.executor.plugins) require the controller to opt in via the ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS environment variable. getExecutorPlugins detects that the workflow declares plugin containers but the controller was started without this flag, and refuses to build the agent pod with a descriptive error.

Source

Thrown at workflow/controller/agent.go:308

		return nil, fmt.Errorf("failed to create Agent pod: %w", err)
	}
	log.Info(ctx, "Created Agent pod")
	return created, nil
}

func (woc *wfOperationCtx) getExecutorPlugins(ctx context.Context) ([]apiv1.Container, []apiv1.Volume, error) {
	var sidecars []apiv1.Container
	var volumes []apiv1.Volume
	namespaces := map[string]bool{} // de-dupes executorPlugins when their namespaces are the same
	namespaces[woc.controller.namespace] = true
	namespaces[woc.wf.Namespace] = true
	wFPlugins, err := woc.execWf.Spec.AsExecutorPluginSpec()
	if err != nil {
		return nil, nil, err
	}
	isGetPluginsFromWorkflow := len(wFPlugins) > 0
	if isGetPluginsFromWorkflow && !woc.controller.enableWorkflowLevelExecutorPlugins {
		return nil, nil, fmt.Errorf(
			"workflow-level executor plugins are disabled in the controller. To enable them, set the environment variable ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true",
		)
	}
	if isGetPluginsFromWorkflow {
		for _, plugin := range wFPlugins {
			sidecar, pluginVolume, err := woc.getExecutorPluginComponents(ctx, plugin)
			if err != nil {
				return nil, nil, err
			}
			sidecars = append(sidecars, *sidecar)
			if pluginVolume != nil {
				volumes = append(volumes, *pluginVolume)
			}
		}
	} else {
		for namespace := range namespaces {
			for _, plug := range woc.controller.executorPlugins[namespace] {
				sidecar, pluginVolume, err := woc.getExecutorPluginComponents(ctx, *plug)

View on GitHub (pinned to 35bff19146)

Solutions

1. Set the env var on the workflow-controller: add `ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS: "true"` to its container env and restart the controller
2. If using Helm/manifests, update the controller values/env config accordingly and redeploy
3. Alternatively remove the executor plugins from the workflow spec if they are not needed
4. Confirm with `kubectl set env deploy/workflow-controller --list -n argo` that the flag took effect

Example fix

# before (controller env)
env: []
# after (controller env)
env:
- name: ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS
  value: "true"

// before submitting a workflow with executor plugins
if pluginsDeclared(wf) && os.Getenv("ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS") != "true" {
    return errors.New("controller must set ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true")
}

When it happens

Trigger: Submitting a workflow whose spec includes `executor: { plugins: [...] }` while the workflow-controller deployment lacks env `ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true`; the controller then fails the workflow during agent pod construction.

Common situations: Upgrading Argo and adopting executor plugins without updating the controller deployment; plugins enabled in one cluster/profile but not another (e.g. staging vs prod controller helm values differ); copying an example workflow that uses plugins into a default-configured cluster.

Related errors

• failed to read container args file %s: %w
• failed to read template: %w
• must specify at least one auth mode
• failed to validate workflow template instanceid: %w
• malformed workflow template parameter "%s": valueFrom is nil

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