theonedev/onedev · error · ExplicitException

Docker container exited with code ${returnCode}

Error message

Docker container exited with code ${returnCode}

What it means

During provisioning, the provisioner runs setup commands inside a docker container via the docker CLI; if the container's exit code is non-zero it throws ExplicitException 'Docker container exited with code N'. This is a failed workspace setup script inside the container.

Source

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

					configFileProvisioner.mountVolumes(docker, workspaceDir, path -> getHostPath(path));

					if (isMountDockerSock()) {
						if (getDockerSockPath() != null)
							docker.addArgs("-v", getDockerSockPath() + ":/var/run/docker.sock");
						else
							docker.addArgs("-v", "/var/run/docker.sock:/var/run/docker.sock");
					}
					if (getRunOptions() != null)
						docker.addArgs(StringUtils.parseQuoteTokens(getRunOptions()));

					for (var entry : envVars.entrySet())
						docker.addArgs("-e", entry.getKey() + "=" + entry.getValue());

					docker.addArgs("--entrypoint", "sh", context.getSpec().getImage(), "-c", entrypointArgs);

					var executeResult = docker.execute(infoLogger, warningLogger);
					if (executeResult.getReturnCode() != 0)
						throw new ExplicitException("Docker container exited with code " + executeResult.getReturnCode());
					return null;
				});
				return null;
			});
			OneDev.getInstance(ExecutorService.class).execute(future);

			try {
				awaitContainerReady(future, containerReadyFile);

				Map<Integer, Integer> portMappings;
				if (!context.getSpec().getContainerPorts().isEmpty())
					portMappings = getPublishedPorts(newDocker(), containerName, context.getSpec().getContainerPorts());
				else
					portMappings = new HashMap<>();

				var portHost = getPortHost();
				var tailscaleIp = getTailscaleIp(newDocker(), containerName,
						context.getScriptConfig(), context.getSpec().getContainerPorts());

View on GitHub (pinned to d44925c47c)

Solutions

1. Check the workspace provisioning logs around the failure for docker/sh stderr output
2. Fix the workspace spec's setup/entrypoint commands and the image so they succeed
3. Test the same command locally: docker run --entrypoint sh <image> -c '<commands>'
4. Verify the docker daemon and disk space on the OneDev server host

Example fix

// before
docker.addArgs("--entrypoint", "sh", image, "-c", "pip install nonexist-pkg");
// after
docker.addArgs("--entrypoint", "sh", image, "-c", "pip install existing-pkg");

// preflight: run the setup commands in the image locally first
// docker run --rm --entrypoint sh <image> -c '<entrypointArgs>' && echo OK

try { provisioner.provision(context, logger); } catch (ExplicitException e) { if (e.getMessage().startsWith('Docker container exited with code')) inspectWorkspaceLogsAndFixSpec(); else throw e; }

When it happens

Trigger: The container entrypoint (sh -c <entrypointArgs>) exits non-zero — setup commands fail, image missing required tools, or docker itself fails to start the container (docker CLI reports an error exit code).

Common situations: Bad base image or missing packages in the setup script; typo in workspace setup commands; image pull failure surfaced as a non-zero docker exit code; out-of-disk on the server.

Related errors

• No applicable provisioner discovered for current workspace.
• This workspace can only be provisioned by shell provisioner
• This workspace can only be provisioned by docker provisioner
• Loopback address not allowed for target docker image of push
• Specified workspace provisioner '${provisioner}' is disabled

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