louislam/dockge · error · Error

Failed to restart, please check the terminal output for more

Error message

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

What it means

Stack.restart() runs 'docker compose restart' and throws this Error when it exits non-zero; details go to the compose terminal. restart re-creates processes in place, so it fails differently from up/down (e.g. it doesn't pull images or apply compose.yaml changes).

Source

Thrown at backend/stack.ts:443

            throw new Error("Failed to start, please check the terminal output for more information.");
        }
        return exitCode;
    }

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

    async restart(socket: DockgeSocket) : Promise<number> {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        let exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", this.getComposeOptions("restart"), this.path);
        if (exitCode !== 0) {
            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.");

View on GitHub (pinned to f809ae192b)

Solutions

  1. Read the compose terminal output for the docker error
  2. If you changed compose.yaml, use Deploy/Up (compose up -d) instead of Restart — restart does not apply config changes
  3. Check host resources (memory/disk) and docker daemon health
  4. Force-recreate via 'docker compose up -d --force-recreate' if restart keeps failing

Example fix

// before
await stack.restart(socket); // config edits not applied, may fail
// after
if (composeYAMLChanged) {
    await stack.deploy(socket); // compose up -d applies changes
} else {
    await stack.restart(socket);
}
Defensive patterns

Strategy: validation

Validate before calling

function needsRecreate(composeYAMLChanged: boolean): boolean {
    // compose restart does NOT apply compose.yaml changes
    return composeYAMLChanged;
}
if (needsRecreate(yamlChanged)) {
    await stack.deploy(socket); // compose up -d applies changes
} else {
    await stack.restart(socket);
}

Type guard

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

Try / catch

try {
    await stack.restart(socket);
} catch (e) {
    log.error("restart", "Restart failed — if compose.yaml changed use deploy (up -d), else check daemon/container state");
    throw e;
}

Prevention

When it happens

Trigger: compose restart exits non-zero: daemon/runtime error, container can't be stopped then started again, compose project lookup fails, resource exhaustion on the host.

Common situations: Restarting after editing compose.yaml expecting changes to apply (restart ignores edits — must deploy/up instead); wedged container after host OOM; daemon hiccup during restart.

Related errors

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