louislam/dockge · error · Error

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

Error message

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

What it means

Stack.update() first runs 'docker compose pull' and throws this Error when the pull exits non-zero, before any restart happens. This is almost always an image fetch problem (registry unreachable, auth failure, bad tag) and the details appear in the compose terminal.

Source

Thrown at backend/stack.ts:461

            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.");
        }
        return exitCode;
    }

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

        // If the stack is not running, we don't need to restart it
        await this.updateStatus();
        log.debug("update", "Status: " + this.status);
        if (this.status !== RUNNING) {
            return exitCode;
        }

        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 restart, please check the terminal output for more information.");
        }
        return exitCode;
    }

    async joinCombinedTerminal(socket: DockgeSocket) {
        const terminalName = getCombinedTerminalName(socket.endpoint, this.name);

View on GitHub (pinned to f809ae192b)

Solutions

  1. Read the compose terminal output in Dockge to see the registry error
  2. Verify the image name/tag exists (docker pull <image> manually)
  3. Fix registry credentials: docker login, or add proper auth for the agent user
  4. Check DNS/outbound connectivity from the agent host (curl the registry)
  5. If rate-limited, authenticate to the registry or wait/backoff before retrying

Example fix

// before
await stack.update(socket);
// after
try {
    await stack.update(socket);
} catch (e) {
    log.error("update", `Pull failed for '${stack.name}' — verify image tags and registry auth (docker login)`);
    throw e;
}
Defensive patterns

Strategy: retry

Validate before calling

import { execSync } from "child_process";
function imagesReachable(dir: string): boolean {
    try { execSync("docker compose pull --quiet", { cwd: dir }); return true; } catch { return false; }
}
if (!imagesReachable(stack.path)) {
    throw new Error("Registry unreachable or auth missing — fix before update");
}
await stack.update(socket);

Type guard

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

Try / catch

try {
    await stack.update(socket);
} catch (e) {
    log.error("update", "Pull failed — verify image tags exist and registry credentials (docker login), check DNS/rate limits, then retry");
    throw e;
}

Prevention

When it happens

Trigger: compose pull exits non-zero: image not found (wrong/removed tag), registry auth required or expired credentials (docker login), DNS/network failure reaching the registry, rate limiting (Docker Hub 429).

Common situations: Using :latest pointing to a deleted tag; private registry with missing/rotated credentials; Docker Hub rate limits; cluster host with broken DNS or no outbound internet; typo in image name in compose.yaml.

Related errors

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