theonedev/onedev · error · ExplicitException

Shell provisioner does not allow absolute cache path:

Error message

Shell provisioner does not allow absolute cache path: 

What it means

ServerShellProvisioner rejects cache configurations whose paths are absolute. Because caching happens inside the workspace directory on the shell host via ServerWorkspaceCacheProvisioner, absolute paths would resolve outside the workspace and break/portability-violate caching. It checks FilenameUtils.getPrefixLength(path) > 0 for each path in each cacheConfig.

Source

Thrown at server-plugin/server-plugin-provisioner-servershell/src/main/java/io/onedev/server/plugin/provisioner/servershell/ServerShellProvisioner.java:167

		var trustCertsFile = new File(workspaceDir, "trust-certs.pem");

		var workDir = getWorkDir(context);
		var envVars = buildEnvVars(
				context.getSpec().getEnvVars().stream()
						.collect(toMap(EnvVar::getName, it -> it.isSecret() ? it.getSecretValue() : it.getValue())),
				context.getServerUrl(), context.getToken(), 
				trustCertsFile.exists()? trustCertsFile.getAbsolutePath(): null,
				workDir.getAbsolutePath());

		workspaceLogger.log("Setting up cache...");

		var cacheProvisioners = new ArrayList<CacheProvisioner>();
		var cacheConfigIndex = 1;
		for (var cacheConfig : context.getSpec().getCacheConfigs()) {
			for (var path : cacheConfig.getPaths()) {
				if (FilenameUtils.getPrefixLength(path) > 0)
					throw new ExplicitException("Shell provisioner does not allow absolute cache path: " + path);
			}
			var cacheProvisioner = new ServerWorkspaceCacheProvisioner(cacheConfig.getFacade(), cacheConfigIndex++, context);
			cacheProvisioner.download(workspaceDir, workspaceLogger);
			cacheProvisioners.add(cacheProvisioner);
		}

		var scriptConfig = context.getScriptConfig();
		setupShellProvisioned(scriptConfig, workspaceDir, envVars, workspaceLogger);

		return new WorkspaceRuntime() {

			@Override
			public GitExecutionResult executeGitCommand(String[] gitArgs) {
				var git = GitUtils.newGit();
				git.workingDir(workDir);
				git.args(Arrays.asList(gitArgs));

				var stdoutStream = new ByteArrayOutputStream();

View on GitHub (pinned to d44925c47c)

Solutions

1. Change the cache path to a workspace-relative path (e.g. '~/.m2/repository' -> '.m2/repository' style relative entry)
2. If absolute storage is required, use a different caching mechanism outside the provisioner cache config
3. Review the agent spec cacheConfigs and strip leading '/' or drive-letter prefixes

Example fix

// before
cacheConfigs:
- paths: ["/opt/cache/m2"]
// after
cacheConfigs:
- paths: ["cache/m2"]

for (var cfg : spec.getCacheConfigs())
  for (var p : cfg.getPaths())
    if (FilenameUtils.getPrefixLength(p) > 0) throw new IllegalArgumentException("Cache path must be relative: " + p);

try { provisioner.provision(ctx, logger); } catch (ExplicitException e) { logger.log(e.getMessage()); }

When it happens

Trigger: provision() iterating spec.getCacheConfigs() where any cacheConfig.getPaths() entry starts with a prefix (e.g. '/home/user/cache', 'C:\cache').

Common situations: Copy-pasting a cache path from a Linux host absolute convention; hardcoding absolute paths when moving pipelines between machines; converting a cache setup written for a docker provisioner (where absolute paths are legal) to server shell.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• This workspace can only be provisioned by docker provisioner
• This workspace is provisioned on agent previously, and canno
• Allocated agent not connected to current server, please retr
• Attachment not found:
• Malformed build spec

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