{"record":{"id":"0af916973e4f63f6","repo":"louislam/dockge","slug":"failed-to-pull-please-check-the-terminal-output-f","errorCode":null,"errorMessage":"Failed to pull, please check the terminal output for more information.","messagePattern":"Failed to pull, please check the terminal output for more information\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"backend/stack.ts","lineNumber":461,"sourceCode":"            throw new Error(\"Failed to restart, please check the terminal output for more information.\");\n        }\n        return exitCode;\n    }\n\n    async down(socket: DockgeSocket) : Promise<number> {\n        const terminalName = getComposeTerminalName(socket.endpoint, this.name);\n        let exitCode = await Terminal.exec(this.server, socket, terminalName, \"docker\", this.getComposeOptions(\"down\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to down, please check the terminal output for more information.\");\n        }\n        return exitCode;\n    }\n\n    async update(socket: DockgeSocket) {\n        const terminalName = getComposeTerminalName(socket.endpoint, this.name);\n        let exitCode = await Terminal.exec(this.server, socket, terminalName, \"docker\", this.getComposeOptions(\"pull\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to pull, please check the terminal output for more information.\");\n        }\n\n        // If the stack is not running, we don't need to restart it\n        await this.updateStatus();\n        log.debug(\"update\", \"Status: \" + this.status);\n        if (this.status !== RUNNING) {\n            return exitCode;\n        }\n\n        exitCode = await Terminal.exec(this.server, socket, terminalName, \"docker\", this.getComposeOptions(\"up\", \"-d\", \"--remove-orphans\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to restart, please check the terminal output for more information.\");\n        }\n        return exitCode;\n    }\n\n    async joinCombinedTerminal(socket: DockgeSocket) {\n        const terminalName = getCombinedTerminalName(socket.endpoint, this.name);","sourceCodeStart":443,"sourceCodeEnd":479,"githubUrl":"https://github.com/louislam/dockge/blob/f809ae192b571944ad773e9866d3e67064ae8043/backend/stack.ts#L443-L479","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the compose terminal output in Dockge to see the registry error","Verify the image name/tag exists (docker pull <image> manually)","Fix registry credentials: docker login, or add proper auth for the agent user","Check DNS/outbound connectivity from the agent host (curl the registry)","If rate-limited, authenticate to the registry or wait/backoff before retrying"],"exampleFix":"// before\nawait stack.update(socket);\n// after\ntry {\n    await stack.update(socket);\n} catch (e) {\n    log.error(\"update\", `Pull failed for '${stack.name}' — verify image tags and registry auth (docker login)`);\n    throw e;\n}","handlingStrategy":"retry","validationCode":"import { execSync } from \"child_process\";\nfunction imagesReachable(dir: string): boolean {\n    try { execSync(\"docker compose pull --quiet\", { cwd: dir }); return true; } catch { return false; }\n}\nif (!imagesReachable(stack.path)) {\n    throw new Error(\"Registry unreachable or auth missing — fix before update\");\n}\nawait stack.update(socket);","typeGuard":"function pullOk(exitCode: number | undefined): boolean {\n    return exitCode === 0;\n}","tryCatchPattern":"try {\n    await stack.update(socket);\n} catch (e) {\n    log.error(\"update\", \"Pull failed — verify image tags exist and registry credentials (docker login), check DNS/rate limits, then retry\");\n    throw e;\n}","preventionTips":["Pin image tags that exist; avoid relying on mutable/deleted tags","Keep registry credentials valid on every agent host","Prefer authenticated pulls to avoid Docker Hub rate limits","Check agent DNS/outbound connectivity before scheduled updates"],"tags":["docker","docker-compose","image-pull","registry","network"],"backgroundTag":"image-pull-failure","analyzedSha":"f809ae192b571944ad773e9866d3e67064ae8043","analyzedAt":"2026-08-31T19:13:50.919Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}