louislam/dockge · error · Error

Failed to start service ${serviceName}, please check logs fo

Error message

Failed to start service ${serviceName}, please check logs for more information.

What it means

Stack.startService() runs `docker compose up -d <serviceName>` in the stack directory via a terminal. A non-zero exit code means docker failed to create/start that single service, so the method throws this template error naming the service. Like other stack errors, the diagnostic detail is in the terminal stream, not in the exception message.

Source

Thrown at backend/stack.ts:558

                    } else {
                        addLine(obj);
                    }
                } catch (e) {
                }
            }

            return statusList;
        } catch (e) {
            log.error("getServiceStatusList", e);
            return statusList;
        }
    }

    async startService(socket: DockgeSocket, serviceName: string) {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        const exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", [ "compose", "up", "-d", serviceName ], this.path);
        if (exitCode !== 0) {
            throw new Error(`Failed to start service ${serviceName}, please check logs for more information.`);
        }

        return exitCode;
    }

    async stopService(socket: DockgeSocket, serviceName: string): Promise<number> {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        const exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", [ "compose", "stop", serviceName ], this.path);
        if (exitCode !== 0) {
            throw new Error(`Failed to stop service ${serviceName}, please check logs for more information.`);
        }

        return exitCode;
    }

    async restartService(socket: DockgeSocket, serviceName: string): Promise<number> {
        const terminalName = getComposeTerminalName(socket.endpoint, this.name);
        const exitCode = await Terminal.exec(this.server, socket, terminalName, "docker", [ "compose", "restart", serviceName ], this.path);

View on GitHub (pinned to f809ae192b)

Solutions

Check the terminal output in Dockge for the docker error for that service
Verify the service name exists: `docker compose config --services` in the stack dir
Run `docker compose up -d <service>` manually to see the full error
Fix the underlying cause (port conflict, bad image, build error) and retry

Example fix

// before
await stack.startService(socket, "web"); // throws if 'web' doesn't exist
// after
const services = await listComposeServices(stack.path);
if (services.includes("web")) {
  await stack.startService(socket, "web");
}

Defensive patterns

Strategy: validation

Validate before calling

const services = (await exec(`docker compose -f ${stack.path}/compose.yml config --services`)).stdout.split(/\s+/).filter(Boolean);
if (!services.includes(serviceName)) {
  throw new Error(`Service '${serviceName}' not in compose file`);
}

Try / catch

try {
  await stack.startService(socket, serviceName);
} catch (e) {
  if (e.message.startsWith("Failed to start service")) {
    console.error(`start failed for ${serviceName}; see terminal output`, e);
  } else throw e;
}

Prevention

List services with `docker compose config --services` before referencing one
Keep the UI service list in sync after editing compose.yml
Pre-pull images (`docker compose pull`) to catch tag/registry problems early
Check for host port conflicts before starting services

When it happens

Trigger: Invoking the start-service socket action for a service whose `docker compose up -d <name>` exits non-zero — e.g. unknown service name in compose file, build failure, pull failure, port conflict, or dependency service failed to start.

Common situations: Typo'd service name sent from the UI after the compose file was edited; image tag no longer exists in the registry; container name or host port already in use; service depends_on a service that fails.

Related errors

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