theonedev/onedev · error · ExplicitException

Step template not found:

Error message

Step template not found: 

What it means

UseTemplateStep reuses actions defined in a named StepTemplate within the same build spec. The template map is resolved from the build spec (build.getSpec().getStepTemplateMap()); if the referenced templateName is absent, this ExplicitException is thrown before any actions are generated.

Source

Thrown at server-core/src/main/java/io/onedev/server/buildspec/step/UseTemplateStep.java:117

	public static List<ParamSpec> getParamSpecs() {
		String templateName = (String) EditContext.get().getInputValue(PROP_TEMPLATE_NAME);
		if (templateName != null) {
			BuildSpec buildSpec = BuildSpec.get();	
			if (buildSpec != null) {
				StepTemplate template = buildSpec.getStepTemplateMap().get(templateName);
				if (template != null)
					return template.getParamSpecs();
			}
		}		
		return new ArrayList<>();
	}
	
	@Override
	protected List<Action> getActions(Build build, JobExecutor jobExecutor, String jobToken, 
								ParamCombination paramCombination) {
		StepTemplate template = build.getSpec().getStepTemplateMap().get(templateName);
		if (template == null)
			throw new ExplicitException("Step template not found: " + templateName);
		
		List<Action> actions = new ArrayList<>();
		AtomicInteger repeatRef = new AtomicInteger(0);
		List<Map<String, List<String>>> paramMaps;
		var projectScopedCommit = new ProjectScopedCommit(build.getProject(), build.getCommitId());
		ProjectScopedCommit.push(projectScopedCommit);
		try {
			paramMaps = resolveParams(build, paramCombination, getParamMatrix(), getExcludeParamMaps());
		} finally {
			ProjectScopedCommit.pop();
		}
		for (var paramMap: paramMaps) {
			int repeat = repeatRef.incrementAndGet();
			ProjectScopedCommit.push(projectScopedCommit);
			try {	
				ParamUtils.validateParamMap(template.getParamSpecs(), paramMap);
			} finally {
				ProjectScopedCommit.pop();

View on GitHub (pinned to d44925c47c)

Solutions

1. Add a StepTemplate with the exact name referenced by templateName to the same build spec.
2. Fix the templateName typo to match an existing template.
3. Copy the template definition over if the step was moved from another build spec/project.
4. Check the spec's templates section parses correctly (indentation) so it lands in getStepTemplateMap().

Example fix

// before
- type: UseTemplate
  templateName: maven-build   # template missing
// after
templates:
- name: maven-build
  steps: !<Steps>
    steps:
    - !<CommandStep>
        ...
- type: UseTemplate
  templateName: maven-build

// Validate before running
var templateMap = build.getSpec().getStepTemplateMap();
if (!templateMap.containsKey(templateName)) {
    throw new ExplicitException("Available templates: " + templateMap.keySet() + "; missing: " + templateName);
}

When it happens

Trigger: A UseTemplateStep whose templateName has no matching 'templates:' entry (StepTemplate) in the build's spec — typically after a typo, deletion, or renaming of the template.

Common situations: Renaming a step template but not all UseTemplateStep references; deleting a template that is still used; copying steps between projects/build specs where the template was not copied; YAML indentation causing the template not to be parsed into the map.

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

• This build is not authorized to sync to project:
• Loopback address not allowed for target docker image of push
• Error validating build spec (project: %s, commit: %s, locati
• Build spec not defined (project: %s, commit: %s)
• Allocated agent not connected to current server, please retr

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