theonedev/onedev · error · ExplicitException

Unrecognized interpolation variable: ${t}

Error message

Unrecognized interpolation variable: ${t}

What it means

WorkspaceVariableInterpolator resolves @...@ tokens in workspace (build context) expressions, supporting built-ins plus script-name variables evaluated via GroovyUtils.evalScriptByName. When a token matches none of the recognized forms, it throws ExplicitException 'Unrecognized interpolation variable'. Like its job counterpart, it is a strict fallback for unknown variable syntax.

Source

Thrown at server-core/src/main/java/io/onedev/server/util/interpolative/WorkspaceVariableInterpolator.java:43

					return value != null ? value : "";
				}
			}
			if (t.startsWith(PREFIX_SCRIPT) || t.startsWith("scripts:")) {
				String scriptName;
				if (t.startsWith(PREFIX_SCRIPT))
					scriptName = t.substring(PREFIX_SCRIPT.length());
				else
					scriptName = t.substring("scripts:".length());

				Map<String, Object> context = new HashMap<>();
				context.put("workspace", workspace);
				Object result = GroovyUtils.evalScriptByName(scriptName, context);
				if (result != null)
					return result.toString();
				else
					return "";
			} else {
				throw new ExplicitException("Unrecognized interpolation variable: " + t);
			}
		});
	}
	
	public WorkspaceVariableInterpolator(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/workspace-variables' target='_blank' tabindex='-1'>insert variable</a>. "
			+ "Use <tt>@@</tt> for literal <tt>@</tt>");
	}

View on GitHub (pinned to d44925c47c)

Solutions

1. Use a variable form supported by the workspace interpolator (built-ins or an existing script name).
2. Ensure the referenced Groovy script exists and is resolvable in the build context if using script variables.
3. Escape literal @ as @@ when the '@' is not meant to start a variable reference.
4. Move job-only prefixes (param/property/secret) to the appropriate interpolator context.

Example fix

// before (workspace context)
String expr = "@param:version@";
// after: use a supported workspace variable or script
String expr = "@version@"; // built-in, or a script named 'version' in context

boolean scriptExists(BuildContext context, String name) {
    try {
        GroovyUtils.evalScriptByName(name, context);
        return true;
    } catch (Exception e) { return false; }
}

try {
    value = workspaceInterpolator.interpolate(expr);
} catch (ExplicitException e) {
    if (e.getMessage().startsWith("Unrecognized interpolation variable")) {
        // use a supported workspace variable or define the script
    } else throw e;
}

When it happens

Trigger: A workspace expression contains '@token@' where 'token' is neither a built-in workspace variable nor the name of a Groovy script resolvable in the context — e.g. using '@param:x@' (job-only prefix) in a workspace expression, or a script name that does not exist / returned a null result path.

Common situations: Copying job-variable expressions into workspace interpolation; referencing a script that was renamed or lives in a different project; typos in built-in variable names; assuming custom variables are available without a resolver.

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/7c9b158dbe205bd7. Report an issue: GitHub.