louislam/dockge · error · Error

${terminalName} Terminal not found.

Error message

${terminalName} Terminal not found.

What it means

After type checks pass, the handler looks the terminal up via Terminal.getTerminal(terminalName); if the result is not a Terminal instance, it throws '<name> Terminal not found.'. This means no terminal with that exact name is registered in this server process (terminals are per-process, in-memory objects tied to stacks/endpoints).

Source

Thrown at backend/agent-socket-handlers/terminal-socket-handler.ts:192

                    throw new Error("Terminal name must be a string.");
                }

                if (typeof rows !== "number") {
                    throw new Error("Command must be a number.");
                }
                if (typeof cols !== "number") {
                    throw new Error("Command must be a number.");
                }

                let terminal = Terminal.getTerminal(terminalName);

                // log.info("terminal", terminal);
                if (terminal instanceof Terminal) {
                    //log.debug("terminalInput", "Terminal found, writing to terminal.");
                    terminal.rows = rows;
                    terminal.cols = cols;
                } else {
                    throw new Error(`${terminalName} Terminal not found.`);
                }
            } catch (e) {
                log.debug("terminalResize",
                        // Added to prevent the lint error when adding the type
                        // and ts type checker saying type is unknown.
                        // @ts-ignore
                        `Error on ${terminalName}: ${e.message}`
                );
            }
        });
    }
}

View on GitHub (pinned to f809ae192b)

Solutions

1. Attach/open the terminal first (the event that creates it) before emitting terminalResize
2. Verify the terminalName matches exactly the one used when the terminal was created
3. In multi-agent setups, ensure the socket is connected to the endpoint that owns the terminal
4. Handle the case where the terminal was destroyed and re-create it

Example fix

// before
socket.emit("terminalResize", oldName, rows, cols); // server restarted, stale name
// after
socket.emit("requestStackList", () => {
    if (hasTerminal(name)) socket.emit("terminalResize", name, rows, cols);
});

const known = await getTerminalNames(); // names the client has successfully opened
if (!known.includes(terminalName)) { console.warn("Terminal not open yet:", terminalName); return; }
socket.emit("terminalResize", terminalName, rows, cols);

// client-side: track terminals you created
const openTerminals = new Set<string>();
const hasTerminal = (name: string): name is string => openTerminals.has(name);

// server logs the error via log.debug; client should confirm terminal creation first
socket.emit("startTerminal", name, ..., (res) => { if (res.ok) socket.emit("terminalResize", name, rows, cols); });

When it happens

Trigger: Emitting terminalResize with a terminalName that was never created, or created on a different agent/endpoint than the one the socket is bound to, or after the stack/terminal was destroyed on the server.

Common situations: Resize sent before the `startTerminal`/attach event completed; multi-agent setups where the client targets the wrong endpoint; server restarted while the client kept a stale terminal name; typo in the stack-generated terminal name.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Terminal name must be a string.
• Command must be a string.
• Terminal not found or it is not a Interactive Terminal.
• Console is not enabled.
• Stack name must be a string.

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