{"record":{"id":"f1d93bbc28c4d8e0","repo":"theonedev/onedev","slug":"step-template-not-found","errorCode":null,"errorMessage":"Step template not found (","messagePattern":"Step template not found \\(","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/buildspec/BuildSpec.java","lineNumber":517,"sourceCode":"\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 + \")\");\n\t\t\t} else {\n\t\t\t\tJob dependencyJob = getJobMap().get(dependency.getJobName());\n\t\t\t\tif (dependencyJob != null) {\n\t\t\t\t\tif (dependencyChain.isEmpty()) {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tParamUtils.validateParamMatrix(dependencyJob.getParamSpecs(), dependency.getParamMatrix());\n\t\t\t\t\t\t\tfor (var paramMap: dependency.getExcludeParamMaps())\n\t\t\t\t\t\t\t\tParamUtils.validateParamMap(dependencyJob.getParamSpecs(), paramMap.getParams());\n\t\t\t\t\t\t} catch (ValidationException e) {","sourceCodeStart":499,"sourceCodeEnd":535,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/buildspec/BuildSpec.java#L499-L535","documentation":"checkTemplateUsages throws ValidationException 'Step template not found (<name>)' when a UseTemplateStep at the top level references a template name absent from the build spec's stepTemplates map. Nested (chained) missing templates are tolerated since only top-level usages are validated directly.","triggerScenarios":"A UseTemplateStep in a job references a templateName that is not defined under stepTemplates in the same build spec (or in the imported spec); occurs during isValid().","commonSituations":"Typo in templateName; deleting a template while jobs still use it; jobs importing templates from another project/branch where the template does not exist; case mismatch in template names.","solutions":["Define the missing template under stepTemplates in the build spec","Correct the templateName in the UseTemplateStep to match an existing template (names are case-sensitive)","If the template lives in another spec being imported, verify the import path/revision resolves and contains the template","Remove the UseTemplateStep if the template is obsolete"],"exampleFix":"# before\nstepTemplates: {}\njobs:\n- name: build\n  steps:\n  - !UseTemplateStep\n    templateName: maven-build   # not defined\n# after\nstepTemplates:\n- name: maven-build\n  steps:\n  - !RunCommandStep\n    commands: mvn package","handlingStrategy":"validation","validationCode":"Map<String, StepTemplate> templates = buildSpec.getStepTemplateMap();\nfor (var job : buildSpec.getJobs())\n    for (var step : job.getSteps())\n        if (step instanceof UseTemplateStep u && !templates.containsKey(u.getTemplateName()))\n            throw new ExplicitException(\"Unknown template: \" + u.getTemplateName());","typeGuard":null,"tryCatchPattern":"try {\n    buildSpec.isValid();\n} catch (ValidationException e) {\n    // 'Step template not found (name)': define or fix the templateName\n}","preventionTips":["Define templates before jobs reference them","Match template names exactly, case included","Delete unused template references when removing templates","Validate imports resolve to specs containing the templates"],"tags":["buildspec","template","validation"],"backgroundTag":"resource-not-found","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"}