louislam/dockge · error · Error

Failed to stop, please check the terminal output for more in

Error message

Failed to stop, please check the terminal output for more information.

What it means

Stack.stop() runs 'docker compose stop' and throws this Error when it exits non-zero. Cause details are printed to the stack's compose terminal.

Source

Thrown at backend/stack.ts:434

        }
        console.log(options);
        return options;
    }

    async start(socket: DockgeSocket) {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        let exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", this.getComposeOptions("up", "-d", "--remove-orphans"), this.path);
        if (exitCode !== 0) {
            throw new Error("Failed to start, please check the terminal output for more information.");
        }
        return exitCode;
    }

    async stop(socket: DockgeSocket) : Promise<number> {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        let exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", this.getComposeOptions("stop"), this.path);
        if (exitCode !== 0) {
            throw new Error("Failed to stop, please check the terminal output for more information.");
        }
        return exitCode;
    }

    async restart(socket: DockgeSocket) : Promise<number> {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        let exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", this.getComposeOptions("restart"), this.path);
        if (exitCode !== 0) {
            throw new Error("Failed to restart, please check the terminal output for more information.");
        }
        return exitCode;
    }

    async down(socket: DockgeSocket) : Promise<number> {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        let exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", this.getComposeOptions("down"), this.path);
        if (exitCode !== 0) {
            throw new Error("Failed to down, please check the terminal output for more information.");

View on GitHub (pinned to f809ae192b)

Solutions

Read the compose terminal output in Dockge for the exact docker error
Check docker daemon health (docker info, systemctl status docker)
Force-remove the stuck container (docker rm -f <container>) then try stop again
If a container ignores SIGTERM, add stop_grace_period in compose.yaml or use docker kill
Restart the Docker daemon if the runtime is wedged

Example fix

// before
await stack.stop(socket);
// after
try {
    await stack.stop(socket);
} catch (e) {
    log.error("stop", `Stop failed for '${stack.name}'; check daemon and consider 'docker rm -f' on stuck containers`);
    throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

function daemonHealthy(): boolean {
    try { execSync("docker info -f '{{.ServerVersion}}'"); return true; } catch { return false; }
}
if (!daemonHealthy()) {
    throw new Error("Docker daemon not responsive — fix daemon before stopping stacks");
}
await stack.stop(socket);

Type guard

function stoppedCleanly(exitCode: number | undefined): boolean {
    return exitCode === 0;
}

Try / catch

try {
    await stack.stop(socket);
} catch (e) {
    log.error("stop", "Stop failed — check daemon, force-remove stuck containers (docker rm -f), then retry");
    throw e;
}

Prevention

Set stop_grace_period for containers that exit slowly
Avoid stopping stacks during daemon restarts/host reboots
Watch for 'dead' container states and clean them up
Keep host disk and memory from being exhausted

When it happens

Trigger: compose stop exits non-zero: docker daemon unresponsive, container in a weird state (dead/unresponsive to SIGTERM/SIGKILL within timeout), compose.yaml/project mismatch, low-level runtime (containerd/runc) error.

Common situations: Host under heavy load causing stop timeout; container with a broken runtime state after an unclean reboot; daemon restart in progress; user deleted compose.yaml so project lookup fails on some setups.

Related errors

AI-assisted analysis of louislam/dockge@f809ae192b (2026-08-31). Data as JSON: /api/errors/a9ddc1d616abe4c1. Report an issue: GitHub.