{"record":{"id":"3c6ae69e11ae3177","repo":"louislam/dockge","slug":"failed-to-deploy-please-check-the-terminal-output","errorCode":null,"errorMessage":"Failed to deploy, please check the terminal output for more information.","messagePattern":"Failed to deploy, please check the terminal output for more information\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"backend/stack.ts","lineNumber":211,"sourceCode":"                throw new ValidationError(\"Stack not found\");\n            }\n        }\n\n        // Write or overwrite the compose.yaml\n        fs.writeFileSync(path.join(dir, this._composeFileName), this.composeYAML);\n        if (process.env.PUID && process.env.PGID) {\n            const uid = Number(process.env.PUID);\n            const gid = Number(process.env.PGID);\n            fs.lchownSync(dir, uid, gid);\n            fs.chownSync(path.join(dir, this._composeFileName), uid, gid);\n        }\n    }\n\n    async deploy(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(\"up\", \"-d\", \"--remove-orphans\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to deploy, please check the terminal output for more information.\");\n        }\n        return exitCode;\n    }\n\n    async delete(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\", \"--remove-orphans\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to delete, please check the terminal output for more information.\");\n        }\n\n        // Remove the stack folder\n        await fsAsync.rm(this.path, {\n            recursive: true,\n            force: true\n        });\n\n        return exitCode;","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/louislam/dockge/blob/f809ae192b571944ad773e9866d3e67064ae8043/backend/stack.ts#L193-L229","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open the stack's terminal in Dockge and read the docker compose error output","Run 'docker compose up -d --remove-orphans' manually in the stack directory to see the full error","Validate compose.yaml (e.g. docker compose config) and fix YAML/env issues","Free the conflicting port or change the host port mapping","Pull images manually (docker compose pull) to check registry access"],"exampleFix":"// before\nawait stack.deploy(socket); // opaque failure\n// after\ntry {\n    await stack.deploy(socket);\n} catch (e) {\n    log.error(\"deploy\", `Compose failed for '${stack.name}': check terminal '${getComposeTerminalName(socket.endpoint, stack.name)}' for docker compose output`);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"import { execSync } from \"child_process\";\nfunction validateCompose(dir: string): boolean {\n    try { execSync(\"docker compose config -q\", { cwd: dir }); return true; }\n    catch { return false; }\n}\nif (!validateCompose(stack.path)) {\n    throw new Error(\"compose.yaml invalid — fix before deploying\");\n}\nawait stack.deploy(socket);","typeGuard":"function isDeploySuccess(exitCode: number | undefined): boolean {\n    return exitCode === 0;\n}","tryCatchPattern":"try {\n    await stack.deploy(socket);\n} catch (e) {\n    log.error(\"deploy\", \"Compose up failed — open the stack terminal for docker output, fix compose.yaml/env, then retry\");\n    throw e;\n}","preventionTips":["Validate compose.yaml (docker compose config) before deploying","Reserve host ports to avoid 'port already allocated'","Pin image tags and pre-pull before deploy","Keep a .env with all interpolated variables present"],"tags":["docker","docker-compose","deployment","terminal"],"backgroundTag":"docker-compose-deploy-failed","analyzedSha":"f809ae192b571944ad773e9866d3e67064ae8043","analyzedAt":"2026-08-31T19:13:50.919Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}