What causes "Unknown job parameter (" in theonedev/onedev?

Fix the parameter name in the caller to match a declared job parameter

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.

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)

Solutions

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

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Keep param names in triggers/dependent jobs in sync with the job spec
Use constants or autocompletion for param names instead of raw strings
Run buildspec validation in CI to catch drift

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

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