{"record":{"id":"49f25fff3358df31","repo":"theonedev/onedev","slug":"docker-container-exited-with-code-returncode","errorCode":null,"errorMessage":"Docker container exited with code ${returnCode}","messagePattern":"Docker container exited with code (.+?)","errorType":"exception","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-plugin/server-plugin-provisioner-serverdocker/src/main/java/io/onedev/server/plugin/provisioner/serverdocker/ServerDockerProvisioner.java","lineNumber":431,"sourceCode":"\t\t\t\t\tconfigFileProvisioner.mountVolumes(docker, workspaceDir, path -> getHostPath(path));\n\n\t\t\t\t\tif (isMountDockerSock()) {\n\t\t\t\t\t\tif (getDockerSockPath() != null)\n\t\t\t\t\t\t\tdocker.addArgs(\"-v\", getDockerSockPath() + \":/var/run/docker.sock\");\n\t\t\t\t\t\telse\n\t\t\t\t\t\t\tdocker.addArgs(\"-v\", \"/var/run/docker.sock:/var/run/docker.sock\");\n\t\t\t\t\t}\n\t\t\t\t\tif (getRunOptions() != null)\n\t\t\t\t\t\tdocker.addArgs(StringUtils.parseQuoteTokens(getRunOptions()));\n\n\t\t\t\t\tfor (var entry : envVars.entrySet())\n\t\t\t\t\t\tdocker.addArgs(\"-e\", entry.getKey() + \"=\" + entry.getValue());\n\n\t\t\t\t\tdocker.addArgs(\"--entrypoint\", \"sh\", context.getSpec().getImage(), \"-c\", entrypointArgs);\n\n\t\t\t\t\tvar executeResult = docker.execute(infoLogger, warningLogger);\n\t\t\t\t\tif (executeResult.getReturnCode() != 0)\n\t\t\t\t\t\tthrow new ExplicitException(\"Docker container exited with code \" + executeResult.getReturnCode());\n\t\t\t\t\treturn null;\n\t\t\t\t});\n\t\t\t\treturn null;\n\t\t\t});\n\t\t\tOneDev.getInstance(ExecutorService.class).execute(future);\n\n\t\t\ttry {\n\t\t\t\tawaitContainerReady(future, containerReadyFile);\n\n\t\t\t\tMap<Integer, Integer> portMappings;\n\t\t\t\tif (!context.getSpec().getContainerPorts().isEmpty())\n\t\t\t\t\tportMappings = getPublishedPorts(newDocker(), containerName, context.getSpec().getContainerPorts());\n\t\t\t\telse\n\t\t\t\t\tportMappings = new HashMap<>();\n\n\t\t\t\tvar portHost = getPortHost();\n\t\t\t\tvar tailscaleIp = getTailscaleIp(newDocker(), containerName,\n\t\t\t\t\t\tcontext.getScriptConfig(), context.getSpec().getContainerPorts());","sourceCodeStart":413,"sourceCodeEnd":449,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-plugin/server-plugin-provisioner-serverdocker/src/main/java/io/onedev/server/plugin/provisioner/serverdocker/ServerDockerProvisioner.java#L413-L449","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the workspace provisioning logs around the failure for docker/sh stderr output","Fix the workspace spec's setup/entrypoint commands and the image so they succeed","Test the same command locally: docker run --entrypoint sh <image> -c '<commands>'","Verify the docker daemon and disk space on the OneDev server host"],"exampleFix":"// before\ndocker.addArgs(\"--entrypoint\", \"sh\", image, \"-c\", \"pip install nonexist-pkg\");\n// after\ndocker.addArgs(\"--entrypoint\", \"sh\", image, \"-c\", \"pip install existing-pkg\");","handlingStrategy":"validation","validationCode":"// preflight: run the setup commands in the image locally first\n// docker run --rm --entrypoint sh <image> -c '<entrypointArgs>' && echo OK","typeGuard":null,"tryCatchPattern":"try { provisioner.provision(context, logger); } catch (ExplicitException e) { if (e.getMessage().startsWith('Docker container exited with code')) inspectWorkspaceLogsAndFixSpec(); else throw e; }","preventionTips":["Test workspace setup commands in the image locally before configuring them","Pin stable base images and verify required tools exist in them","Monitor server disk space and docker daemon health"],"tags":["docker","provisioner","exit-code"],"backgroundTag":"command-exited-nonzero","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}