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.
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.
How to fix it
- 01Open a new terminal. The old ptyID no longer refers to a live process, so no operation against it will succeed.
- 02Read 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.
- 03If 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.
- 04Do not reuse a ptyID across an Atlas restart. The ptyID is not durable, so an id captured before a restart produces Pty.NotFoundError afterwards.
- 05Open a terminal in Atlas and confirm it accepts input without raising Pty.NotFoundError or Pty.ExitedError.
Frequently asked questions
- 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Code Llama (local via Ollama): a Fill-in-the-Middle Baseline in 2026
Code Llama runs free and local via Ollama at 7b, 13b, 34b, and 70b with a 16,384 token context. Strong at infilling, but too small and too old for Atlas agent work.
Atlas vs Devin: AI Coding Agents Compared for 2026
Atlas and Devin offer distinct AI coding experiences in 2026. Atlas provides a terminal-native TUI with local control, while Devin is a cloud-managed engineer with SWE-1.7.
Atlas vs Warp: Choosing Your AI Coding Agent in 2026
Compare Atlas, the terminal-native AI coding agent, with Warp, a smart terminal with AI Agent Mode, for developers in 2026. Evaluate features, privacy, and workflow.
Atlas for PHP in 2026
Atlas, the terminal-native AI coding agent, empowers PHP developers in 2026 with intelligent code understanding, secure workflows, and direct integration for Composer and PSR standards.
Atlas vs Amp: Terminal AI Coding Agents in 2026
Compare Atlas, a terminal-native AI coding agent with free core and local embeddings, against Amp, Sourcegraph's agent featuring Oracle and Orbs, for developers in 2026.
Onboard to an Unfamiliar Codebase with Atlas in 2026
How to onboard to an unfamiliar codebase with Atlas in 2026: use codebase_search, glob, read, lsp, task, and todowrite to build a mental model fast.
Atlas for Haskell in 2026
Atlas is a terminal-native AI coding agent for Haskell in 2026. Run it in a project with a .cabal file or a stack.yaml, let cabal build drive it, and review the diff.
Atlas for Express in 2026
Atlas is a terminal-native AI coding agent for Express in 2026. It reads your middleware order, wraps async route handlers, and runs mocha behind a prompt.