theonedev/onedev · error · ExplicitException

Undefined param: ${paramName}

Error message

Undefined param: ${paramName}

What it means

JobVariableInterpolator resolves @param:...@ references in job/CI variable expressions against the parameters declared for the build. When the referenced parameter name is not defined for the job/build, it throws ExplicitException 'Undefined param'. The interpolator is strict: only parameters known at build time may be referenced.

Source

Thrown at server-core/src/main/java/io/onedev/server/util/interpolative/JobVariableInterpolator.java:70

				String paramName;
				if (t.startsWith(PREFIX_PARAM))
					paramName = t.substring(PREFIX_PARAM.length());
				else
					paramName = t.substring("params:".length());

				for (Entry<String, Input> entry : paramCombination.getParamInputs().entrySet()) {
					if (paramName.equals(entry.getKey())) {
						String paramType = entry.getValue().getType();
						List<String> paramValues = new ArrayList<>();
						for (String value : entry.getValue().getValues()) {
							if (paramType.equals(ParamSpec.SECRET))
								value = build.getJobAuthorizationContext().getSecretValue(value);
							paramValues.add(value);
						}
						return StringUtils.join(paramValues, ",");
					}
				}
				throw new ExplicitException("Undefined param: " + paramName);
			} else if (t.startsWith(PREFIX_PROPERTY) || t.startsWith("properties:")) {
				String propertyName;
				if (t.startsWith(PREFIX_PROPERTY))
					propertyName = t.substring(PREFIX_PROPERTY.length());
				else
					propertyName = t.substring("properties:".length());

				JobProperty property = build.getSpec().getPropertyMap().get(propertyName);
				if (property != null) {
					return property.getValue();
				} else {
					for (var projectProperty : build.getProject().getHierarchyJobProperties()) {
						if (projectProperty.getName().equals(propertyName))
							return projectProperty.getValue();
					}
					throw new ExplicitException("Undefined property: " + propertyName);
				}
			} else if (t.startsWith(PREFIX_SECRET) || t.startsWith("secrets:")) {

View on GitHub (pinned to d44925c47c)

Solutions

1. Add the missing parameter to the job's parameter definitions so '@param:name@' resolves.
2. Correct the parameter name in the interpolation expression to match the declared parameter.
3. Remove the stale @param:...@ reference if the parameter is no longer needed.
4. If the parameter may be absent, restructure the expression to avoid depending on it or define it with a default value.

Example fix

// before (parameter 'buildNumber' was renamed to 'build_number')
String expr = "@param:buildNumber@";
// after
String expr = "@param:build_number@";

boolean paramDefined(Build build, String name) {
    return build.getJob().getParams().stream()
        .anyMatch(p -> p.getName().equals(name));
}

try {
    value = interpolate("@param:foo@");
} catch (ExplicitException e) {
    if (e.getMessage().startsWith("Undefined param")) {
        value = defaultValue; // or surface a config error to the user
    } else throw e;
}

When it happens

Trigger: An expression like '@param:myParam@' (or 'params:myParam') where 'myParam' is not among the build's declared job parameters — e.g. the parameter was renamed/deleted in the job definition while variable expressions still reference it, or the build was run without that parameter.

Common situations: Renaming a job parameter but not updating interpolation expressions; referencing a parameter of a parent job from a child build; typo in the parameter name; running an old build/spec that references removed parameters.

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

• Undefined property: ${propertyName}
• Unrecognized interpolation variable: ${t}
• Unrecognized interpolation variable: ${t}
• Unrecognized interpolation variable: ${t}
• Unrecognized interpolation variable: ${t}

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