theonedev/onedev · error · ValidationException

Step template not found (

Error message

Step template not found (

What it means

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.

Source

Thrown at server-core/src/main/java/io/onedev/server/buildspec/BuildSpec.java:517

		} else {
			StepTemplate template = getStepTemplateMap().get(step.getTemplateName());
			if (template != null) {
				if (templateChain.isEmpty()) {
					try {
						ParamUtils.validateParamMatrix(template.getParamSpecs(), step.getParamMatrix());
						for (var paramMap: step.getExcludeParamMaps())
							ParamUtils.validateParamMap(template.getParamSpecs(), paramMap.getParams());
					} catch (Exception e) {
						throw new ValidationException(String.format("Error validating step template parameters (%s)", e.getMessage()));
					}
				}
				templateChain.add(step.getTemplateName());
				for (Step templateStep: template.getSteps()) {
					if (templateStep instanceof UseTemplateStep) 
						checkTemplateUsages((UseTemplateStep) templateStep, new ArrayList<>(templateChain));
				}
			} else if (templateChain.isEmpty()) {
				throw new ValidationException("Step template not found (" + step.getTemplateName() + ")");
			}
		}
	}
	
	private void checkDependencies(Job job, List<String> dependencyChain) {
		for (JobDependency dependency: job.getJobDependencies()) {
			if (dependencyChain.contains(dependency.getJobName())) {
				dependencyChain.add(dependency.getJobName());
				throw new ValidationException("Circular dependencies (" + dependencyChain + ")");
			} else {
				Job dependencyJob = getJobMap().get(dependency.getJobName());
				if (dependencyJob != null) {
					if (dependencyChain.isEmpty()) {
						try {
							ParamUtils.validateParamMatrix(dependencyJob.getParamSpecs(), dependency.getParamMatrix());
							for (var paramMap: dependency.getExcludeParamMaps())
								ParamUtils.validateParamMap(dependencyJob.getParamSpecs(), paramMap.getParams());
						} catch (ValidationException e) {

View on GitHub (pinned to d44925c47c)

Solutions

  1. Define the missing template under stepTemplates in the build spec
  2. Correct the templateName in the UseTemplateStep to match an existing template (names are case-sensitive)
  3. If the template lives in another spec being imported, verify the import path/revision resolves and contains the template
  4. Remove the UseTemplateStep if the template is obsolete

Example fix

# before
stepTemplates: {}
jobs:
- name: build
  steps:
  - !UseTemplateStep
    templateName: maven-build   # not defined
# after
stepTemplates:
- name: maven-build
  steps:
  - !RunCommandStep
    commands: mvn package
Defensive patterns

Strategy: validation

Validate before calling

Map<String, StepTemplate> templates = buildSpec.getStepTemplateMap();
for (var job : buildSpec.getJobs())
    for (var step : job.getSteps())
        if (step instanceof UseTemplateStep u && !templates.containsKey(u.getTemplateName()))
            throw new ExplicitException("Unknown template: " + u.getTemplateName());

Try / catch

try {
    buildSpec.isValid();
} catch (ValidationException e) {
    // 'Step template not found (name)': define or fix the templateName
}

Prevention

When it happens

Trigger: 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().

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/f1d93bbc28c4d8e0. Report an issue: GitHub.