theonedev/onedev · error · ValidationException

Error validating step template parameters (%s)

Error message

Error validating step template parameters (%s)

What it means

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.

Source

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

		if (!isValid)
			context.disableDefaultConstraintViolation();
		return isValid;
	}
	
	private void checkTemplateUsages(UseTemplateStep step, List<String> templateChain) {
		if(templateChain.contains(step.getTemplateName())) {
			templateChain.add(step.getTemplateName());
			throw new ValidationException("Circular template usages (" + templateChain + ")");
		} 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 + ")");

View on GitHub (pinned to d44925c47c)

Solutions

1. Read the inner error message to see which parameter is rejected, then fix the paramMatrix in the UseTemplateStep
2. Update the template's paramSpecs if the new parameter usage is intended
3. Remove excludeParamMaps entries referencing parameters that no longer exist on the template
4. Re-validate the spec in the build spec editor which shows param errors inline

Example fix

# before: template defines param 'env' but usage omits it
- !UseTemplateStep
  templateName: deploy
  paramMatrix: {}
# after
- !UseTemplateStep
  templateName: deploy
  paramMatrix:
    env: production

// compare template.paramSpecs names with every key used in step.getParamMatrix()
// and in each excludeParamMap before saving the spec

try {
    buildSpec.isValid();
} catch (ValidationException e) {
    // message contains the underlying param validation error; fix the paramMatrix
}

When it happens

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

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

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Circular template usages (
• Step template not found (
• Circular dependencies (
• Error validating dependency job parameters (dependency job:
• Dependency job not found (

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