# Atlas Pty.NotFoundError and Pty.ExitedError: the terminal exited or was not found > Open a new terminal. The old ptyID no longer refers to a live process, and a ptyID is not durable across an Atlas restart. Atlas raises Pty.NotFoundError for a given ptyID when no terminal with that id exists, and Pty.ExitedError when the process behind the terminal has already exited, so the fix in both cases is to open a new terminal, because the old ptyID no longer refers to a live process. Atlas's PTY service models a missing terminal and an exited terminal as two separate tagged errors, each carrying the ptyID, and publishes pty.exited events with the exit code, so read the pty.exited event's exitCode to see why the shell died. Do not reuse a ptyID across an Atlas restart: the id is not durable. ## Symptom A terminal operation in Atlas fails with Pty.NotFoundError for the given ptyID, or with Pty.ExitedError when the process behind that terminal has already exited. The terminal pane stops responding to input. ## Cause Atlas's PTY service models a missing terminal and an exited terminal as two separate tagged errors, each carrying the ptyID, and publishes pty.exited events with the exit code. Pty.NotFoundError means no terminal with that ptyID exists at all. Pty.ExitedError means the terminal existed but its process is gone, commonly because the shell died on startup or was closed. ## Fix 1. Open a new terminal. The old ptyID no longer refers to a live process, so no operation against it will succeed. 2. Read the pty.exited event's exitCode to see why the shell died. Atlas publishes pty.exited events with the exit code for exactly this purpose. 3. If the shell exits immediately on open, check your login shell's rc files for a failing command, since a bad rc file kills the shell before it can accept input. 4. Do not reuse a ptyID across an Atlas restart. The ptyID is not durable, so an id captured before a restart produces Pty.NotFoundError afterwards. 5. Open a terminal in Atlas and confirm it accepts input without raising Pty.NotFoundError or Pty.ExitedError. ## What is the difference between Pty.NotFoundError and Pty.ExitedError in Atlas Atlas's PTY service models a missing terminal and an exited terminal as 2 separate tagged errors, each carrying the ptyID. Pty.NotFoundError means no terminal with that ptyID exists. Pty.ExitedError means a terminal with that ptyID did exist, but the process behind it has already exited. The split is deliberate. A missing terminal and a dead terminal need different reasoning: Pty.NotFoundError usually points at a stale or invented ptyID, often one held across an Atlas restart, while Pty.ExitedError points at a shell that started and then died. Both errors carry the ptyID, so the id in the message is the one Atlas was asked about. In both cases the practical fix is the same, open a new terminal, but the diagnosis you do afterwards is different. ## How to read the pty.exited event exitCode in Atlas Atlas publishes pty.exited events with the exit code, so read the pty.exited event's exitCode to see why the shell died. When Atlas raises Pty.ExitedError for a ptyID, the matching pty.exited event carries the status the shell process returned, and a status other than 0 is the actual diagnosis. The exitCode is the shell's own exit status, not an Atlas code, so it means whatever your shell means by it. A shell that dies during startup typically exits non-zero, which is a strong hint that the failure is in the shell's initialization rather than in Atlas's PTY service. Atlas keeps the exit code on the pty.exited event rather than burying it, precisely so a terminal that vanishes is explainable after the fact instead of being a mystery. ## Why does my Atlas terminal exit immediately on open An Atlas terminal that exits immediately on open almost always means your login shell died during startup, so check your login shell's rc files for a failing command. Atlas raises Pty.ExitedError for the ptyID and publishes a pty.exited event carrying the exit code, so a code other than 0 confirms the shell, not Atlas, ended the session. A single failing line in a shell rc file, such as a command that no longer exists, a path that has moved, or a script that exits on error, will kill the shell before it ever draws a prompt. Because Atlas spawns your real login shell, a broken rc file breaks Atlas terminals exactly as it breaks a normal terminal. Test by starting your login shell directly from another terminal. If it dies there too, the fix belongs in the rc file, not in Atlas. ## Why a ptyID stops working after restarting Atlas A ptyID stops working after an Atlas restart because the id is not durable. The new Atlas process has 0 terminals registered under that id, so any operation against it raises Pty.NotFoundError carrying the ptyID you supplied. Open a new terminal rather than reusing an id from a previous run. PTY ids identify live terminals inside a running Atlas process, not persistent records. Restarting Atlas tears down every terminal, and the new process starts with an empty PTY registry. Any script, plugin, or client that caches a ptyID and replays it later will hit Pty.NotFoundError. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, so if a plugin holds terminal ids, it needs to open a new terminal after a restart rather than reusing an old id. ## How to verify the terminal works again Verify an Atlas terminal fix by opening a new terminal and running 1 simple command in it. Atlas raises Pty.NotFoundError only for an unknown ptyID and Pty.ExitedError only for a process that has already exited, so a terminal that accepts input and returns output has neither problem. If a freshly opened terminal still dies, read the pty.exited event's exitCode again: the number will have been published for the new terminal too, and a repeat non-zero exit confirms the shell's rc files are still failing. If the new terminal works but an older operation still raises Pty.NotFoundError, something in your workflow is holding the stale ptyID. Point it at the new terminal instead, since the old id is gone for good. ## FAQ ### What does Pty.NotFoundError mean in Atlas? Pty.NotFoundError means no terminal with the given ptyID exists in Atlas. It usually means the ptyID is stale, often held across an Atlas restart. Open a new terminal, because the ptyID is not durable. ### What does Pty.ExitedError mean in Atlas? Pty.ExitedError means the process behind the terminal has already exited. Atlas publishes pty.exited events with the exit code, so read the pty.exited event's exitCode to see why the shell died. ### Why does my Atlas terminal close as soon as it opens? The shell most likely died during startup. Check your login shell's rc files for a failing command, and read the pty.exited event's exitCode, which Atlas publishes with the shell's exit status. ### Can I reuse an Atlas ptyID after restarting Atlas? No. Do not reuse a ptyID across an Atlas restart, because the id is not durable. The new Atlas process has no terminal under that id, so any operation raises Pty.NotFoundError. ### How do I find the exit code of a dead Atlas terminal? Read the pty.exited event. Atlas's PTY service publishes pty.exited events with the exit code, and that number is the shell's own exit status rather than an Atlas code. ### Why does Atlas have two separate PTY errors instead of one? Atlas's PTY service models a missing terminal and an exited terminal as two separate tagged errors, each carrying the ptyID, because a stale id and a dead shell need different diagnoses even though both are fixed by opening a new terminal. ### Does opening a new Atlas terminal lose my session? No. A terminal is not the session. Opening a new terminal after Pty.NotFoundError or Pty.ExitedError gives you a live shell again while your Atlas session continues as it was. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/pty-exited-or-not-found Source of truth: aeo_pages row `/resources/troubleshooting/pty-exited-or-not-found` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.