{"record":{"id":"956383bad373b117","repo":"theonedev/onedev","slug":"error-validating-step-template-parameters-s","errorCode":null,"errorMessage":"Error validating step template parameters (%s)","messagePattern":"Error validating step template parameters \\((.+?)\\)","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/buildspec/BuildSpec.java","lineNumber":508,"sourceCode":"\t\tif (!isValid)\n\t\t\tcontext.disableDefaultConstraintViolation();\n\t\treturn isValid;\n\t}\n\t\n\tprivate void checkTemplateUsages(UseTemplateStep step, List<String> templateChain) {\n\t\tif(templateChain.contains(step.getTemplateName())) {\n\t\t\ttemplateChain.add(step.getTemplateName());\n\t\t\tthrow new ValidationException(\"Circular template usages (\" + templateChain + \")\");\n\t\t} else {\n\t\t\tStepTemplate template = getStepTemplateMap().get(step.getTemplateName());\n\t\t\tif (template != null) {\n\t\t\t\tif (templateChain.isEmpty()) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tParamUtils.validateParamMatrix(template.getParamSpecs(), step.getParamMatrix());\n\t\t\t\t\t\tfor (var paramMap: step.getExcludeParamMaps())\n\t\t\t\t\t\t\tParamUtils.validateParamMap(template.getParamSpecs(), paramMap.getParams());\n\t\t\t\t\t} catch (Exception e) {\n\t\t\t\t\t\tthrow new ValidationException(String.format(\"Error validating step template parameters (%s)\", e.getMessage()));\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\ttemplateChain.add(step.getTemplateName());\n\t\t\t\tfor (Step templateStep: template.getSteps()) {\n\t\t\t\t\tif (templateStep instanceof UseTemplateStep) \n\t\t\t\t\t\tcheckTemplateUsages((UseTemplateStep) templateStep, new ArrayList<>(templateChain));\n\t\t\t\t}\n\t\t\t} else if (templateChain.isEmpty()) {\n\t\t\t\tthrow new ValidationException(\"Step template not found (\" + step.getTemplateName() + \")\");\n\t\t\t}\n\t\t}\n\t}\n\t\n\tprivate void checkDependencies(Job job, List<String> dependencyChain) {\n\t\tfor (JobDependency dependency: job.getJobDependencies()) {\n\t\t\tif (dependencyChain.contains(dependency.getJobName())) {\n\t\t\t\tdependencyChain.add(dependency.getJobName());\n\t\t\t\tthrow new ValidationException(\"Circular dependencies (\" + dependencyChain + \")\");","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/buildspec/BuildSpec.java#L490-L526","documentation":"When a UseTemplateStep references a template whose parameters do not match, checkTemplateUsages wraps the underlying ParamUtils validation error in a ValidationException 'Error validating step template parameters (<cause>)'. This surfaces param matrix / param map mismatches against the template's param specs.","triggerScenarios":"Using a step template with a paramMatrix containing params not declared in the template's paramSpecs, missing required params, or excludeParamMaps with unknown parameter names; only checked at the outermost level (empty template chain).","commonSituations":"Template author added/renamed a required param and existing usages broke; passing a value for a param the template no longer defines; wrong choice values for a param with a fixed set of options.","solutions":["Read the inner error message to see which parameter is rejected, then fix the paramMatrix in the UseTemplateStep","Update the template's paramSpecs if the new parameter usage is intended","Remove excludeParamMaps entries referencing parameters that no longer exist on the template","Re-validate the spec in the build spec editor which shows param errors inline"],"exampleFix":"# before: template defines param 'env' but usage omits it\n- !UseTemplateStep\n  templateName: deploy\n  paramMatrix: {}\n# after\n- !UseTemplateStep\n  templateName: deploy\n  paramMatrix:\n    env: production","handlingStrategy":"validation","validationCode":"// compare template.paramSpecs names with every key used in step.getParamMatrix()\n// and in each excludeParamMap before saving the spec","typeGuard":null,"tryCatchPattern":"try {\n    buildSpec.isValid();\n} catch (ValidationException e) {\n    // message contains the underlying param validation error; fix the paramMatrix\n}","preventionTips":["Keep template paramSpecs in sync with all usages","When adding a required param to a template, update every UseTemplateStep","Prefer editor UI autocomplete for parameter names","Remove stale excludeParamMaps entries"],"tags":["buildspec","template","parameters","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}