{"record":{"id":"a3bb857a919db840","repo":"louislam/dockge","slug":"terminalname-terminal-not-found","errorCode":null,"errorMessage":"${terminalName} Terminal not found.","messagePattern":"(.+?) Terminal not found\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"backend/agent-socket-handlers/terminal-socket-handler.ts","lineNumber":192,"sourceCode":"                    throw new Error(\"Terminal name must be a string.\");\n                }\n\n                if (typeof rows !== \"number\") {\n                    throw new Error(\"Command must be a number.\");\n                }\n                if (typeof cols !== \"number\") {\n                    throw new Error(\"Command must be a number.\");\n                }\n\n                let terminal = Terminal.getTerminal(terminalName);\n\n                // log.info(\"terminal\", terminal);\n                if (terminal instanceof Terminal) {\n                    //log.debug(\"terminalInput\", \"Terminal found, writing to terminal.\");\n                    terminal.rows = rows;\n                    terminal.cols = cols;\n                } else {\n                    throw new Error(`${terminalName} Terminal not found.`);\n                }\n            } catch (e) {\n                log.debug(\"terminalResize\",\n                        // Added to prevent the lint error when adding the type\n                        // and ts type checker saying type is unknown.\n                        // @ts-ignore\n                        `Error on ${terminalName}: ${e.message}`\n                );\n            }\n        });\n    }\n}\n","sourceCodeStart":174,"sourceCodeEnd":205,"githubUrl":"https://github.com/louislam/dockge/blob/f809ae192b571944ad773e9866d3e67064ae8043/backend/agent-socket-handlers/terminal-socket-handler.ts#L174-L205","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Attach/open the terminal first (the event that creates it) before emitting terminalResize","Verify the terminalName matches exactly the one used when the terminal was created","In multi-agent setups, ensure the socket is connected to the endpoint that owns the terminal","Handle the case where the terminal was destroyed and re-create it"],"exampleFix":"// before\nsocket.emit(\"terminalResize\", oldName, rows, cols); // server restarted, stale name\n// after\nsocket.emit(\"requestStackList\", () => {\n    if (hasTerminal(name)) socket.emit(\"terminalResize\", name, rows, cols);\n});","handlingStrategy":"validation","validationCode":"const known = await getTerminalNames(); // names the client has successfully opened\nif (!known.includes(terminalName)) { console.warn(\"Terminal not open yet:\", terminalName); return; }\nsocket.emit(\"terminalResize\", terminalName, rows, cols);","typeGuard":"// client-side: track terminals you created\nconst openTerminals = new Set<string>();\nconst hasTerminal = (name: string): name is string => openTerminals.has(name);","tryCatchPattern":"// server logs the error via log.debug; client should confirm terminal creation first\nsocket.emit(\"startTerminal\", name, ..., (res) => { if (res.ok) socket.emit(\"terminalResize\", name, rows, cols); });","preventionTips":["Only resize terminals after the create/attach event acknowledged success","Clear cached terminal names when the server or stack restarts","In multi-agent mode, scope terminal names per endpoint"],"tags":["terminal","socket-io","state-management","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"f809ae192b571944ad773e9866d3e67064ae8043","analyzedAt":"2026-08-31T19:13:50.919Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}