theonedev/onedev · error · ValidationException

Unknown job parameter (

Error message

Unknown job parameter (

What it means

Thrown by ParamUtils.validateParamNames when a supplied parameter name does not correspond to any parameter declared in the job's param specs. OneDev rejects unexpected parameters to avoid silently ignoring typos.

Solutions

1. Fix the parameter name in the caller to match a declared job parameter
2. Remove the extraneous parameter from the map/matrix
3. Update the job's param specs if the parameter is legitimately new

Example fix

// before
params: {verison: "1.0"}
// after
params: {version: "1.0"}

Set<String> specNames = paramSpecs.stream().map(ParamSpec::getName).collect(Collectors.toSet());
paramMap.keySet().retainAll(specNames); // or fail fast on unknown keys

try { ParamUtils.validateParamMap(specs, paramMap); } catch (ValidationException e) { if (e.getMessage().startsWith("Unknown job parameter")) { /* fix or drop that key */ } }

When it happens

Trigger: Calling validateParamMatrix or validateParamMap with a param map/matrix key that is not in paramSpecs — e.g. passing 'verison' when the job defines 'version'.

Common situations: Typo in parameter name; job spec was edited to remove/rename a param while triggers or dependent jobs still pass the old name; copy-pasted param blocks between jobs.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• At least one value needs to be specified
• Duplicate values not allowed
• Error validating param value
• Error validating param values
• Missing job parameter (

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

Appendix: source

Thrown at server-core/src/main/java/io/onedev/server/buildspec/param/ParamUtils.java:103

						displayValue.add(each);
				}
			} else {
				displayValue = paramValue;
			}
			String errorMessage = String.format("Error validating param value (param: %s, value: %s, error message: %s", 
					paramName, displayValue, e.getMessage() != null? e.getMessage(): e.getClass());
			throw new ValidationException(errorMessage);
		}
	}

	private static void validateParamNames(Collection<String> paramSpecNames, Collection<String> paramNames) {
		for (String paramSpecName: paramSpecNames) {
			if (!paramNames.contains(paramSpecName))
				throw new ValidationException("Missing job parameter (" + paramSpecName + ")");
		}
		for (String paramName: paramNames) {
			if (!paramSpecNames.contains(paramName))
				throw new ValidationException("Unknown job parameter (" + paramName + ")");
		}
	}
	
	public static void validateParamMap(List<ParamSpec> paramSpecs, Map<String, List<String>> paramMap) {
		Map<String, ParamSpec> paramSpecMap = ParamUtils.getParamSpecMap(paramSpecs);
		validateParamNames(paramSpecMap.keySet(), paramMap.keySet());
		for (Map.Entry<String, List<String>> entry: paramMap.entrySet()) {
			if (entry.getValue() != null) {
				ParamSpec paramSpec = Preconditions.checkNotNull(paramSpecMap.get(entry.getKey()));
				validateParamValue(paramSpec, entry.getKey(), entry.getValue());
			}
		}
	}
	
	public static Map<String, ParamSpec> getParamSpecMap(List<ParamSpec> paramSpecs) {
		Map<String, ParamSpec> paramSpecMap = new LinkedHashMap<>();
		for (ParamSpec paramSpec: paramSpecs)
			paramSpecMap.put(paramSpec.getName(), paramSpec);

View on GitHub (pinned to d44925c47c)