{"record":{"id":"6e60c017d7af5e1a","repo":"argoproj/argo-workflows","slug":"s-q-is-not-a-workflowspec-field-name","errorCode":null,"errorMessage":"%s: %q is not a WorkflowSpec field name","messagePattern":"(.+?): %q is not a WorkflowSpec field name","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"workflow/util/merge.go","lineNumber":90,"sourceCode":"\t// Map YAML/JSON name -> Go field name; allowedUserOverrideFields is keyed by Go name.\n\tgoName := map[string]string{}\n\tt := reflect.TypeFor[wfv1.WorkflowSpec]()\n\tfor field := range t.Fields() {\n\t\tname, _, _ := strings.Cut(field.Tag.Get(\"json\"), \",\")\n\t\tif name == \"\" || name == \"-\" {\n\t\t\tname = field.Name // ponytail: fall back to Go name for any untagged field\n\t\t}\n\t\tgoName[name] = field.Name\n\t}\n\tvar fields []string\n\tfor f := range strings.SplitSeq(env, \",\") {\n\t\tf = strings.TrimSpace(f)\n\t\tif f == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\tg, ok := goName[f]\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%s: %q is not a WorkflowSpec field name\", userOverrideAllowlistEnv, f)\n\t\t}\n\t\tfields = append(fields, g)\n\t}\n\treturn fields, nil\n}\n\n// ValidateUserOverrides checks that a user-submitted WorkflowSpec only sets\n// fields from the allow-list. Returns an error listing all violations.\nfunc ValidateUserOverrides(userSpec *wfv1.WorkflowSpec) error {\n\tif userSpec == nil {\n\t\treturn nil\n\t}\n\tv := reflect.ValueOf(userSpec).Elem()\n\tt := v.Type()\n\tzero := reflect.New(t).Elem()\n\n\tvar violations []string\n\tfor i := 0; i < t.NumField(); i++ {","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/argoproj/argo-workflows/blob/35bff19146f5a6ada77468c431f2624bd577e373/workflow/util/merge.go#L72-L108","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the offending field name in the env var to match a real WorkflowSpec field name exactly (JSON name, e.g. 'entrypoint', 'serviceAccountName')","Check against the WorkflowSpec schema (api/jsonschema or docs/fields.md) for valid names","Remove stale/unknown entries that no longer exist in your Argo version"],"exampleFix":"// before\nARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST=entryPont,serviceAccountName\n// after\nARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST=entrypoint,serviceAccountName","handlingStrategy":"validation","validationCode":"fields := strings.Split(os.Getenv(\"ARGO_WORKFLOW_SPEC_USE_TEMPLATEREF_ALLOWLIST\"), \",\")\nfor _, f := range fields {\n    f = strings.TrimSpace(f)\n    if f != \"\" && !workflowSpecJSONFields[f] {\n        return fmt.Errorf(\"%q is not a WorkflowSpec field name\", f)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := util.ConfigureUserOverrideAllowlistFromEnv(ctx); err != nil {\n    log.Fatalf(\"invalid allowlist env var, fix field names: %v\", err)\n}","preventionTips":["Source allowlist entries from docs/fields.md or the generated JSON schema, not from memory","Test controller startup with the env var in a staging environment before rollout","Pin and review the allowlist value whenever upgrading Argo versions"],"tags":["configuration","env-var","validation","workflow-spec"],"backgroundTag":"invalid-env-var-value","analyzedSha":"35bff19146f5a6ada77468c431f2624bd577e373","analyzedAt":"2026-09-03T19:34:35.908Z","contentChangedAt":"2026-09-03T19:34:35.908Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}