louislam/dockge · error · Error

Failed to start, please check the terminal output for more i

Error message

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

What it means

Stack.start() runs 'docker compose up -d --remove-orphans' and throws this Error when it exits non-zero. Unlike deploy, the stack folder already exists; failure is in compose bringing services up. Details appear in the attached compose terminal.

Source

Thrown at backend/stack.ts:425

    getComposeOptions(command : string, ...extraOptions : string[]) {
        //--env-file ./../global.env --env-file .env
        let options = [ "compose", command, ...extraOptions ];
        if (fs.existsSync(path.join(this.server.stacksDir, "global.env"))) {
            if (fs.existsSync(path.join(this.path, ".env"))) {
                options.splice(1, 0, "--env-file", "./.env");
            }
            options.splice(1, 0, "--env-file", "../global.env");
        }
        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.");

View on GitHub (pinned to f809ae192b)

Solutions

  1. Open the stack terminal in Dockge to read the docker compose error
  2. Run 'docker compose config' in the stack dir to validate compose.yaml
  3. Check port conflicts (docker ps / ss -tlnp) and adjust mappings
  4. Pull images explicitly (docker compose pull) to surface registry/auth problems
  5. Check docker daemon health (systemctl status docker / docker info)

Example fix

// before
await stack.start(socket);
// after
try {
    await stack.start(socket);
} catch (e) {
    log.error("start", `Start failed for '${stack.name}' — inspect the compose terminal output for the docker error`);
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

import { execSync } from "child_process";
function composeConfigValid(dir: string): boolean {
    try { execSync("docker compose config -q", { cwd: dir }); return true; } catch { return false; }
}
if (!composeConfigValid(stack.path)) {
    throw new Error("Fix compose.yaml before starting");
}
await stack.start(socket);

Type guard

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

Try / catch

try {
    await stack.start(socket);
} catch (e) {
    log.error("start", "Start failed — read the compose terminal: check compose.yaml, ports, image availability, daemon health");
    throw e;
}

Prevention

When it happens

Trigger: compose up fails: invalid compose.yaml after an edit, image pull failure, port conflict, dependency service unhealthy, container name conflict with an orphaned container, resource limits (no memory/disk).

Common situations: Editing compose.yaml with a typo then pressing Start; pulling an image tag that no longer exists; host port taken by another service; docker daemon degraded after update.

Related errors

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