Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Clarify Docker permission errors in dev script (#403)

Graham Neubig2b40e3425e9b
diff --git a/__tests__/scripts/dev-docker.test.ts b/__tests__/scripts/dev-docker.test.ts
index 27bc1d82b1..f920db9284 100644
--- a/__tests__/scripts/dev-docker.test.ts
+++ b/__tests__/scripts/dev-docker.test.ts
@@ -1,6 +1,9 @@
import { describe, expect, it } from "vitest";
-import { CONTAINER_WORKSPACES_DIR } from "../../scripts/dev-docker.mjs";
+import {
+ CONTAINER_WORKSPACES_DIR,
+ isDockerPermissionDenied,
+} from "../../scripts/dev-docker.mjs";
describe("CONTAINER_WORKSPACES_DIR", () => {
it("points at the dockerized agent-server's in-container persistence dir so the working_dir the GUI sends is one the container can mkdir (regression guard for the host-path leak that caused 500 on POST /api/conversations)", () => {
@@ -9,3 +12,21 @@ describe("CONTAINER_WORKSPACES_DIR", () => {
);
});
});
+
+describe("isDockerPermissionDenied", () => {
+ it("detects Linux docker socket permission failures", () => {
+ expect(
+ isDockerPermissionDenied(
+ "permission denied while trying to connect to the docker API at unix:///var/run/docker.sock",
+ ),
+ ).toBe(true);
+ });
+
+ it("does not treat a missing daemon as a permission failure", () => {
+ expect(
+ isDockerPermissionDenied(
+ "failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running",
+ ),
+ ).toBe(false);
+ });
+});
diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjs
index 7b35ff9aef..db55242f12 100644
--- a/scripts/dev-docker.mjs
+++ b/scripts/dev-docker.mjs
@@ -110,6 +110,40 @@ function suggestDockerless() {
logError("Note: this runs the agent with full access to your filesystem.");
}
+function isDockerPermissionDenied(stderr) {
+ const normalized = stderr.toLowerCase();
+ return (
+ normalized.includes("permission denied") &&
+ (normalized.includes("docker.sock") ||
+ normalized.includes("docker api") ||
+ normalized.includes("/var/run/docker") ||
+ normalized.includes("/run/docker"))
+ );
+}
+
+function logDockerInfoFailure(stderr) {
+ if (isDockerPermissionDenied(stderr)) {
+ logError(
+ "docker is installed and the daemon may be running, but this user cannot access the Docker API.",
+ );
+ if (stderr) {
+ logError(` ${stderr.split("\n")[0]}`);
+ }
+ logError(
+ "On Linux, add your user to the docker group, then log out and back in:",
+ );
+ logError(" sudo usermod -aG docker $USER");
+ logError("Verify with: docker info");
+ return;
+ }
+
+ logError("docker is installed but the daemon does not appear to be running.");
+ if (stderr) {
+ logError(` ${stderr.split("\n")[0]}`);
+ }
+ logError("Start Docker (e.g. open Docker Desktop) and try again.");
+}
+
/**
* Check that the docker CLI is on PATH AND that the docker daemon is
* actually responding. `commandExists("docker")` only verifies the binary is
@@ -132,14 +166,8 @@ function checkDockerPrereqs(config) {
timeout: 10_000,
});
if (info.status !== 0) {
- logError(
- "docker is installed but the daemon does not appear to be running.",
- );
const stderr = info.stderr ? info.stderr.toString().trim() : "";
- if (stderr) {
- logError(` ${stderr.split("\n")[0]}`);
- }
- logError("Start Docker (e.g. open Docker Desktop) and try again.");
+ logDockerInfoFailure(stderr);
suggestDockerless();
process.exit(1);
}
@@ -297,6 +325,7 @@ export {
CONTAINER_WORKSPACES_DIR,
DEFAULT_AGENT_SERVER_TAG,
checkDockerPrereqs,
+ isDockerPermissionDenied,
resolveAgentServerImage,
startAgentServerDocker,
};