theonedev/onedev · error · ExplicitException

This workspace can only be provisioned by shell provisioner

Error message

This workspace can only be provisioned by shell provisioner

What it means

ServerDockerProvisioner.provision throws ExplicitException when the workspace spec has isRunInContainer() == false. A spec that does not run in a container must be handled by the shell provisioner, not the server docker provisioner.

Source

Thrown at server-plugin/server-plugin-provisioner-serverdocker/src/main/java/io/onedev/server/plugin/provisioner/serverdocker/ServerDockerProvisioner.java:296

		@Editable
		@OmitName
		@NotEmpty
		public String getDockerImage() {
			return dockerImage;
		}

		public void setDockerImage(String dockerImage) {
			this.dockerImage = dockerImage;
		}

	}

	@Override
	public WorkspaceRuntime provision(WorkspaceContext context, TaskLogger workspaceLogger) {		
		checkApplicable();

		if (!context.getSpec().isRunInContainer()) 
			throw new ExplicitException("This workspace can only be provisioned by shell provisioner");

		var serverAddress = getClusterService().getLocalServerAddress();
		workspaceLogger.log("Provisioning workspace on server '" + serverAddress + "'...");
		ServerProvisionerUtils.persistServerAddress(context.getWorkspaceId(), serverAddress);		

		var workspaceDir = ServerProvisionerUtils.getWorkspaceDir(context);
		FileUtils.createDir(workspaceDir);

		var osIds = getOsIds(workspaceLogger);
		if (SystemUtils.IS_OS_LINUX && !osIds.equals("0:0")) {
			workspaceLogger.log("Changing owner of workspace directory to host user...");		
			changeOwner(newDocker(), osIds, workspaceDir, osIds, workspaceLogger);
		}

		var allRegistryLogins = getAllRegistryLogins(context);

		var infoLogger = AgentUtils.newInfoLogger(workspaceLogger);
		var warningLogger = AgentUtils.newWarningLogger(workspaceLogger);

View on GitHub (pinned to d44925c47c)

Solutions

Enable 'run in container' and set a docker image on the workspace spec
Or switch the workspace's provisioner to Server Shell provisioner
Re-run the workspace provisioning after updating the spec

Example fix

// before
spec.setRunInContainer(false); // assigned to ServerDockerProvisioner
// after
spec.setRunInContainer(true);
spec.setImage("python:3.11");

Defensive patterns

Strategy: validation

Validate before calling

if (!context.getSpec().isRunInContainer()) { throw new IllegalStateException('Assign this workspace to the Server Shell provisioner or enable runInContainer'); }

Try / catch

try { provisioner.provision(context, logger); } catch (ExplicitException e) { if (e.getMessage().contains('shell provisioner')) switchProvisionerOrFixSpec(); else throw e; }

Prevention

Match provisioner type to the workspace spec's run-in-container setting
Set a container image whenever using docker-based provisioners
Review workspace specs after copying configs between projects

When it happens

Trigger: A workspace/build spec whose environment is configured to run on the server directly (no container image) but is assigned to the Server Docker provisioner.

Common situations: Spec created for server-shell execution later reassigned to docker provisioner; copy-pasted workspace config without setting an image/run-in-container flag.

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