fields %v are not permitted when using workflowTemplateRef w

Error message

fields %v are not permitted when using workflowTemplateRef with templateReferencing restriction

What it means

When a workflow uses workflowTemplateRef with the templateReferencing restriction, ValidateUserOverrides rejects any user-supplied spec fields that are not on the operator-configured allowlist. The error lists all violating field names. Notably ArtifactGC overrides are always flagged because PodSpecPatch/PodMetadata inside ArtifactGC could reach the artifact-GC Pod and re-open privilege escalation.

Source

Thrown at workflow/util/merge.go:125

	var violations []string
	for i := 0; i < t.NumField(); i++ {
		fieldName := t.Field(i).Name
		if allowedUserOverrideFields[fieldName] {
			continue
		}
		if !reflect.DeepEqual(v.Field(i).Interface(), zero.Field(i).Interface()) {
			violations = append(violations, fieldName)
		}
	}
	// ArtifactGC is allow-listed so that its benign fields (Strategy,
	// ForceFinalizerRemoval) may be set, but its nested ServiceAccountName,
	// PodSpecPatch and PodMetadata reach the artifact-GC Pod and would otherwise
	// re-open the privilege escalation that the top-level ServiceAccountName /
	// PodSpecPatch / PodMetadata blocks are meant to close, so reject them here.
	violations = append(violations, artifactGCOverrideViolations(userSpec.ArtifactGC)...)
	if len(violations) > 0 {
		sort.Strings(violations)
		return fmt.Errorf("fields %v are not permitted when using workflowTemplateRef with templateReferencing restriction", violations)
	}
	return nil
}

// SanitizeUserWorkflowSpec returns a copy of userSpec with only allow-listed
// fields preserved. This provides defense-in-depth after validation.
func SanitizeUserWorkflowSpec(userSpec *wfv1.WorkflowSpec) *wfv1.WorkflowSpec {
	if userSpec == nil {
		return nil
	}
	sanitized := &wfv1.WorkflowSpec{}
	src := reflect.ValueOf(userSpec).Elem()
	dst := reflect.ValueOf(sanitized).Elem()
	t := src.Type()

	for i := 0; i < t.NumField(); i++ {
		if allowedUserOverrideFields[t.Field(i).Name] {
			dst.Field(i).Set(src.Field(i))

View on GitHub (pinned to 35bff19146)

Solutions

Remove the disallowed fields from the submitted workflow spec and put those settings in the referenced WorkflowTemplate instead
Ask the operator to add the needed fields to the templateReferencing allowlist env var if the overrides are legitimately required
Remove spec.artifactGC podSpecPatch/podMetadata overrides — these are always rejected in restriction mode

Example fix

// before
spec:
  workflowTemplateRef:
    name: mytpl
  serviceAccountName: privileged-sa
// after
spec:
  workflowTemplateRef:
    name: mytpl  # SA set inside the template

Defensive patterns

Strategy: validation

Validate before calling

restricted := usesTemplateRefWithRestriction(wf)
if restricted {
    for _, f := range disallowedOverrideFields(wf.Spec) {
        return fmt.Errorf("field %q not permitted with templateReferencing restriction", f)
    }
}

Try / catch

err := util.ValidateUserOverrides(spec, tmplSpec)
if err != nil && strings.Contains(err.Error(), "not permitted when using workflowTemplateRef") {
    // move those settings into the referenced WorkflowTemplate
}

Prevention

Design restricted-mode templates to contain all pod-level settings (SA, securityContext)
Never set spec.artifactGC.podSpecPatch/podMetadata in restricted-mode submissions
Document the allowlist to workflow authors so overrides are designed, not guessed

When it happens

Trigger: Submitting a workflow with workflowTemplateRef (restriction mode) whose spec sets fields outside the allowlist — e.g. spec.podSpecPatch, spec.podMetadata, spec.serviceAccountName, or spec.artifactGC with podSpecPatch/podMetadata — and ValidateUserOverrides is invoked (submit path / tests).

Common situations: Users adding per-workflow tweaks (securityContext, SA, pod metadata) while the operator has locked down template referencing; ArtifactGC settings in a restricted submit; allowlist env var not covering fields the team expects.

Related errors

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