louislam/dockge · error · Error

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

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.

Solutions

Open the stack terminal in Dockge to read the docker compose error
Run 'docker compose config' in the stack dir to validate compose.yaml
Check port conflicts (docker ps / ss -tlnp) and adjust mappings
Pull images explicitly (docker compose pull) to surface registry/auth problems
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

Validate compose.yaml after every edit before starting
Pre-pull images (compose pull) to catch registry issues early
Avoid host port conflicts across stacks
Monitor docker daemon health and disk space

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.

Appendix: 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)