louislam/dockge · error · Error

Failed to deploy, please check the terminal output for more

Error message

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

What it means

Stack.deploy() runs 'docker compose up -d --remove-orphans' via Terminal.exec; a non-zero exit code means the compose project failed to come up, and this Error is thrown. The real cause (build failure, invalid YAML, bad image, port conflict) is printed in the interactive terminal attached to the socket.

Source

Thrown at backend/stack.ts:211

                throw new ValidationError("Stack not found");
            }
        }

        // Write or overwrite the compose.yaml
        fs.writeFileSync(path.join(dir, this._composeFileName), this.composeYAML);
        if (process.env.PUID && process.env.PGID) {
            const uid = Number(process.env.PUID);
            const gid = Number(process.env.PGID);
            fs.lchownSync(dir, uid, gid);
            fs.chownSync(path.join(dir, this._composeFileName), uid, gid);
        }
    }

    async deploy(socket : DockgeSocket) : Promise<number> {
        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 deploy, please check the terminal output for more information.");
        }
        return exitCode;
    }

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

        // Remove the stack folder
        await fsAsync.rm(this.path, {
            recursive: true,
            force: true
        });

        return exitCode;

View on GitHub (pinned to f809ae192b)

Solutions

  1. Open the stack's terminal in Dockge and read the docker compose error output
  2. Run 'docker compose up -d --remove-orphans' manually in the stack directory to see the full error
  3. Validate compose.yaml (e.g. docker compose config) and fix YAML/env issues
  4. Free the conflicting port or change the host port mapping
  5. Pull images manually (docker compose pull) to check registry access

Example fix

// before
await stack.deploy(socket); // opaque failure
// after
try {
    await stack.deploy(socket);
} catch (e) {
    log.error("deploy", `Compose failed for '${stack.name}': check terminal '${getComposeTerminalName(socket.endpoint, stack.name)}' for docker compose output`);
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

import { execSync } from "child_process";
function validateCompose(dir: string): boolean {
    try { execSync("docker compose config -q", { cwd: dir }); return true; }
    catch { return false; }
}
if (!validateCompose(stack.path)) {
    throw new Error("compose.yaml invalid — fix before deploying");
}
await stack.deploy(socket);

Type guard

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

Try / catch

try {
    await stack.deploy(socket);
} catch (e) {
    log.error("deploy", "Compose up failed — open the stack terminal for docker output, fix compose.yaml/env, then retry");
    throw e;
}

Prevention

When it happens

Trigger: docker compose up exits non-zero: malformed compose.yaml (schema error), missing/invalid env interpolation, image pull failure, port already allocated, build error, network conflict with --remove-orphans removing dependent containers.

Common situations: Typo or unsupported key in compose.yaml; unbound variable ${VAR} without a .env; published port colliding with another container; referencing an image that doesn't exist in the registry; insufficient disk space.

Related errors

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