{"record":{"id":"8d1f2ba9c65ce14e","repo":"louislam/dockge","slug":"failed-to-start-please-check-the-terminal-output","errorCode":null,"errorMessage":"Failed to start, please check the terminal output for more information.","messagePattern":"Failed to start, please check the terminal output for more information\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"backend/stack.ts","lineNumber":425,"sourceCode":"\n    getComposeOptions(command : string, ...extraOptions : string[]) {\n        //--env-file ./../global.env --env-file .env\n        let options = [ \"compose\", command, ...extraOptions ];\n        if (fs.existsSync(path.join(this.server.stacksDir, \"global.env\"))) {\n            if (fs.existsSync(path.join(this.path, \".env\"))) {\n                options.splice(1, 0, \"--env-file\", \"./.env\");\n            }\n            options.splice(1, 0, \"--env-file\", \"../global.env\");\n        }\n        console.log(options);\n        return options;\n    }\n\n    async start(socket: DockgeSocket) {\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 start, please check the terminal output for more information.\");\n        }\n        return exitCode;\n    }\n\n    async stop(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(\"stop\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to stop, please check the terminal output for more information.\");\n        }\n        return exitCode;\n    }\n\n    async restart(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(\"restart\"), this.path);\n        if (exitCode !== 0) {\n            throw new Error(\"Failed to restart, please check the terminal output for more information.\");","sourceCodeStart":407,"sourceCodeEnd":443,"githubUrl":"https://github.com/louislam/dockge/blob/f809ae192b571944ad773e9866d3e67064ae8043/backend/stack.ts#L407-L443","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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)"],"exampleFix":"// before\nawait stack.start(socket);\n// after\ntry {\n    await stack.start(socket);\n} catch (e) {\n    log.error(\"start\", `Start failed for '${stack.name}' — inspect the compose terminal output for the docker error`);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"import { execSync } from \"child_process\";\nfunction composeConfigValid(dir: string): boolean {\n    try { execSync(\"docker compose config -q\", { cwd: dir }); return true; } catch { return false; }\n}\nif (!composeConfigValid(stack.path)) {\n    throw new Error(\"Fix compose.yaml before starting\");\n}\nawait stack.start(socket);","typeGuard":"function canStart(exitCode: number | undefined): boolean {\n    return exitCode === 0;\n}","tryCatchPattern":"try {\n    await stack.start(socket);\n} catch (e) {\n    log.error(\"start\", \"Start failed — read the compose terminal: check compose.yaml, ports, image availability, daemon health\");\n    throw e;\n}","preventionTips":["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"],"tags":["docker","docker-compose","start","terminal"],"backgroundTag":"docker-compose-up-failed","analyzedSha":"f809ae192b571944ad773e9866d3e67064ae8043","analyzedAt":"2026-08-31T19:13:50.919Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}