theonedev/onedev · error · ExplicitException

Unrecognized interpolation variable: ${t}

Error message

Unrecognized interpolation variable: ${t}

What it means

JobVariableInterpolator maps each interpolation token to a known prefix (param, property, secret, file, attribute, pause, etc.). When a token matches none of the recognized prefixes/forms, the resolver throws ExplicitException 'Unrecognized interpolation variable'. This is a fallback guard for tokens the current interpolator context cannot resolve.

Source

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

					scriptName = t.substring(PREFIX_SCRIPT.length());
				else
					scriptName = t.substring("scripts:".length());

				Map<String, Object> context = new HashMap<>();
				context.put("build", build);
				Object result = GroovyUtils.evalScriptByName(scriptName, context);
				if (result != null)
					return result.toString();
				else
					return "";
			} else if (t.startsWith(PREFIX_FILE)) {
				return PLACEHOLDER_PREFIX + WORKDIR + "/" + t.substring(PREFIX_FILE.length()) + PLACEHOLDER_SUFFIX;
			} else if (t.startsWith(PREFIX_ATTRIBUTE)) {
				return PLACEHOLDER_PREFIX + ATTRIBUTES + "/" + t.substring(PREFIX_ATTRIBUTE.length()) + PLACEHOLDER_SUFFIX;
			} else if (t.equals(JobHelper.PAUSE)) {
				return PLACEHOLDER_PREFIX + JobHelper.PAUSE + PLACEHOLDER_SUFFIX;
			} else {
				throw new ExplicitException("Unrecognized interpolation variable: " + t);
			}
		});
	}
	
	public JobVariableInterpolator(Function<String, String> variableResolver) {
		this.variableResolver = variableResolver;
	}
		
	@Override
	protected Function<String, String> getVariableResolver() {
		return variableResolver;
	}

	public static String getHelp() {
		return _T("<b>Tips: </b> Type <tt>@</tt> to <a href='https://docs.onedev.io/appendix/job-variables' target='_blank' tabindex='-1'>insert variable</a>. "
			+ "Use <tt>@@</tt> for literal <tt>@</tt>");
	}

View on GitHub (pinned to d44925c47c)

Solutions

1. Correct the token to a supported variable form (e.g. @param:x@, @property:x@, @secret:x@, @file:x@, @attribute:x@).
2. Check which interpolator context you are in and use only variables supported there.
3. Escape literal @ as @@ if the text was never meant to be an interpolation variable.
4. Consult the OneDev variable documentation for the exact built-in names in your version.

Example fix

// before
String expr = "@myvar@"; // not a built-in job variable
// after
String expr = "@param:myvar@"; // reference a declared job parameter

private static final Set<String> JOB_PREFIXES = Set.of(
    "param:", "params:", "property:", "properties:",
    "secret:", "secrets:", "file:", "attribute:", "attributes:");
boolean recognizedJobVariable(String t) {
    return JOB_PREFIXES.stream().anyMatch(t::startsWith);
}

try {
    value = jobInterpolator.interpolate(expr);
} catch (ExplicitException e) {
    if (e.getMessage().startsWith("Unrecognized interpolation variable")) {
        // fix expression or escape @ as @@
    } else throw e;
}

When it happens

Trigger: An @...@ token whose content is not a supported variable form for job variable interpolation — e.g. '@unknown:foo@', a bare token like '@foo@' that is not a built-in variable name, or a valid prefix for a different interpolator (e.g. workspace-only script variables) used in the job-variable context.

Common situations: Typos in built-in variable names; copying expressions between OneDev interpolator contexts (job vs workspace) where supported prefixes differ; inventing custom variable syntax without registering a resolver; version changes that renamed built-in variables.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Undefined param: ${paramName}
• Undefined property: ${propertyName}
• 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/86c4295bf1d90415. Report an issue: GitHub.