argoproj/argo-workflows · error

%s: %q is not a WorkflowSpec field name

Error message

%s: %q is not a WorkflowSpec field name

What it means

ARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST (userOverrideAllowlistEnv) lets operators restrict which WorkflowSpec fields users may override when using workflowTemplateRef. parseUserOverrideAllowlist maps each user-supplied JSON/YAML field name to its Go struct field name; an entry that is not a real WorkflowSpec field name is rejected at configuration (startup) time.

Source

Thrown at workflow/util/merge.go:90

	// Map YAML/JSON name -> Go field name; allowedUserOverrideFields is keyed by Go name.
	goName := map[string]string{}
	t := reflect.TypeFor[wfv1.WorkflowSpec]()
	for field := range t.Fields() {
		name, _, _ := strings.Cut(field.Tag.Get("json"), ",")
		if name == "" || name == "-" {
			name = field.Name // ponytail: fall back to Go name for any untagged field
		}
		goName[name] = field.Name
	}
	var fields []string
	for f := range strings.SplitSeq(env, ",") {
		f = strings.TrimSpace(f)
		if f == "" {
			continue
		}
		g, ok := goName[f]
		if !ok {
			return nil, fmt.Errorf("%s: %q is not a WorkflowSpec field name", userOverrideAllowlistEnv, f)
		}
		fields = append(fields, g)
	}
	return fields, nil
}

// ValidateUserOverrides checks that a user-submitted WorkflowSpec only sets
// fields from the allow-list. Returns an error listing all violations.
func ValidateUserOverrides(userSpec *wfv1.WorkflowSpec) error {
	if userSpec == nil {
		return nil
	}
	v := reflect.ValueOf(userSpec).Elem()
	t := v.Type()
	zero := reflect.New(t).Elem()

	var violations []string
	for i := 0; i < t.NumField(); i++ {

View on GitHub (pinned to 35bff19146)

Solutions

1. Fix the offending field name in the env var to match a real WorkflowSpec field name exactly (JSON name, e.g. 'entrypoint', 'serviceAccountName')
2. Check against the WorkflowSpec schema (api/jsonschema or docs/fields.md) for valid names
3. Remove stale/unknown entries that no longer exist in your Argo version

Example fix

// before
ARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST=entryPont,serviceAccountName
// after
ARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST=entrypoint,serviceAccountName

fields := strings.Split(os.Getenv("ARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST"), ",")
for _, f := range fields {
    f = strings.TrimSpace(f)
    if f != "" && !workflowSpecJSONFields[f] {
        return fmt.Errorf("%q is not a WorkflowSpec field name", f)
    }
}

if err := util.ConfigureUserOverrideAllowlistFromEnv(ctx); err != nil {
    log.Fatalf("invalid allowlist env var, fix field names: %v", err)
}

When it happens

Trigger: The environment variable for the allowlist contains an entry (after trimming) that does not match any WorkflowSpec JSON field name, causing ConfigureUserOverrideAllowlistFromEnv to return this error, typically at controller/server startup.

Common situations: Typos in field names in the env var (e.g. 'entryPont', 'servicaccount'); using Go-style names instead of JSON names or vice versa; stale entries after a version change renamed/removed a field; stray whitespace/empty handling is fine but garbage tokens fail.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• CodeBadRequest
• successCondition, failureCondition and outputs are not suppo
• malformed workflow template parameter "%s": valueFrom is nil
• maxRetries cannot be less than 0
• baseDelay cannot be less than 0

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