{"record":{"id":"59a2463d120b8666","repo":"argoproj/argo-workflows","slug":"workflows-must-use-workflowtemplateref-to-be-execu","errorCode":null,"errorMessage":"workflows must use workflowTemplateRef to be executed when the controller is in reference mode","messagePattern":"workflows must use workflowTemplateRef to be executed when the controller is in reference mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"workflow/controller/operator.go","lineNumber":4502,"sourceCode":"\t\t// When workflow restrictions require template referencing (Strict/Secure mode),\n\t\t// reject workflows that set any non-allowed fields, as they could override\n\t\t// security settings defined in the WorkflowTemplate.\n\t\tif woc.controller.Config.WorkflowRestrictions.MustUseReference() { // not-woc-misuse: intentionally checking the user-submitted spec\n\t\t\tif err := wfutil.ValidateUserOverrides(&woc.wf.Spec); err != nil { //nolint:forbidigo // not-woc-misuse\n\t\t\t\tctx = woc.markWorkflowError(ctx, err)\n\t\t\t\treturn ctx, err\n\t\t\t}\n\t\t}\n\t\terr := woc.setStoredWfSpec(ctx)\n\t\tif err != nil {\n\t\t\tctx = woc.markWorkflowError(ctx, err)\n\t\t\treturn ctx, err\n\t\t}\n\t\twoc.execWf = &wfv1.Workflow{Spec: *woc.wf.Status.StoredWorkflowSpec.DeepCopy()}\n\t\twoc.volumes = woc.execWf.Spec.DeepCopy().Volumes\n\t\tsetWfTemplateLabel(woc.wf)\n\tcase woc.controller.Config.WorkflowRestrictions.MustUseReference():\n\t\terr := fmt.Errorf(\"workflows must use workflowTemplateRef to be executed when the controller is in reference mode\")\n\t\tctx = woc.markWorkflowError(ctx, err)\n\t\treturn ctx, err\n\tdefault:\n\t\terr := woc.controller.setWorkflowDefaults(woc.wf)\n\t\tif err != nil {\n\t\t\tctx = woc.markWorkflowError(ctx, err)\n\t\t\treturn ctx, err\n\t\t}\n\t\twoc.volumes = woc.wf.Spec.DeepCopy().Volumes //nolint:forbidigo // not-woc-misuse\n\t}\n\n\t// Perform one-time workflow validation\n\tif woc.wf.Status.Phase == wfv1.WorkflowUnknown {\n\t\tvalidateOpts := validate.Opts{}\n\t\twftmplGetter := templateresolution.WrapWorkflowTemplateInterface(woc.controller.wfclientset.ArgoprojV1alpha1().WorkflowTemplates(woc.wf.Namespace))\n\t\tcwftmplGetter := templateresolution.WrapClusterWorkflowTemplateInterface(woc.controller.wfclientset.ArgoprojV1alpha1().ClusterWorkflowTemplates())\n\n\t\t// Validate the execution wfSpec","sourceCodeStart":4484,"sourceCodeEnd":4520,"githubUrl":"https://github.com/argoproj/argo-workflows/blob/35bff19146f5a6ada77468c431f2624bd577e373/workflow/controller/operator.go#L4484-L4520","documentation":"When the controller is configured with workflowRestrictions.templateReferencing: Strict/Secure (reference mode), it rejects any workflow that does not use workflowTemplateRef. The reconciliation marks the workflow Error with this message and returns it.","triggerScenarios":"Submitting a workflow with an inline spec (no spec.workflowTemplateRef) to a controller whose config sets workflowRestrictions.templateReferencing, causing MustUseReference() to be true during operate().","commonSituations":"Namespace-wide policy enforcement enabled but legacy inline-spec workflows still exist; CI pipelines submitting hand-written specs after an admin hardened the controller config.","solutions":["Set spec.workflowTemplateRef.name on the workflow, moving its spec content into a WorkflowTemplate","Remove or relax the workflowRestrictions.templateReferencing setting in the controller ConfigMap if inline specs are allowed","Update CI/templates so all submissions go through WorkflowTemplates"],"exampleFix":"// before (controller config)\nworkflowRestrictions:\n  templateReferencing: Strict\n// with inline-spec workflow -> either remove restriction or use:\n// after\nspec:\n  workflowTemplateRef:\n    name: my-template","handlingStrategy":"validation","validationCode":"if controllerConfig.WorkflowRestrictions != nil && wf.Spec.WorkflowTemplateRef == nil {\n    return fmt.Errorf(\"reference mode enabled: workflow must use workflowTemplateRef\")\n}","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"reference mode\") {\n    // resubmit using a WorkflowTemplate reference\n}","preventionTips":["Know your controller's workflowRestrictions config","Standardize submissions through WorkflowTemplates","Add CI linting that requires workflowTemplateRef in restricted namespaces"],"tags":["kubernetes","argo-workflows","policy","workflow-template"],"backgroundTag":"controller-reference-mode-violation","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"}