Skip to content
AtlasDocs

Troubleshooting

Most problems say what they are, in the app or in the terminal. This page gathers the common ones, what causes each and the way out. Each guide also has a section of its own for its subject.

Start here

  • The log is logs/atlas.log in your home (~/.atlas/logs/atlas.log by default), with every secret masked. ATLAS_LOG_LEVEL=DEBUG makes it say more.
  • atlas version prints the version you run, and atlas models check checks every key with its provider, spending nothing.
  • The documentation of your version is on your machine too: atlas docs --search WORDS.

Installing

  • The install folder is taken by something that is not an installation of Atlas: the installer never writes over a folder it did not make. Move that folder away and run the line again.
  • The path is too long (Windows): an install folder longer than 120 characters is refused before anything is downloaded, since Git for Windows cannot unpack past that.
  • “musl” or “libatomic” (Linux): the Node Atlas pins does not run on that system, and the installer stops before downloading anything.
  • The app does not open on Linux after installing: Electron’s sandbox helper needs to be owned by root. The installer does it with sudo when it can, and otherwise prints the two commands to run.
  • A download failed or a hash did not match: nothing was installed with it. Run the line again; it repairs and goes on from where it stopped.

The first start

  • The app opens on “Connect a model provider”: Atlas has no key yet. Paste one, or choose I’ll choose later and come back from the band at the top (Models and keys).
  • A key is refused: the provider answered 401 or 403. Make a new key on its page.
  • Atlas answers that its quota is used up: the provider’s limit or credit, not Atlas’s. Add credit, wait for the quota to come back, or switch the conversation to another provider.

Coding agents

  • A harness shows “not found on this computer”: install it as its line in Settings, then Executors says, then Look again.
  • “Not logged in”: choose Log in, which opens the harness’s own login in your browser.
  • “This session is open in a terminal”: the same session is still open in another program. Continue in a copy is the safe choice; two programs writing one session mix up its messages.
  • The session stopped at its plan’s limit: give it a route, or switch its account (Coding agents and accounts).

Updating

  • It refuses while the app is open: atlas update from a terminal needs the app closed, since the app’s servers run from the installation. The app’s own Update and reopen closes it for you.
  • It refuses an installation with changes of its own: someone edited the installation’s files. Atlas never overwrites them: undo them, or keep them and update with Git yourself.
  • The update failed: Atlas went back to the version it was on, and the app said why. Your data is untouched, and a database is backed up before each migration.

Other machines

  • “Waiting for Tailscale”: Tailscale is not running, or this machine is not on your tailnet. Open Tailscale and sign in with the same account on both machines.
  • The code is refused: the other machine’s password changed since the code was made. Copy a new code there (Open to my machines, or atlas server code).
  • An SSH tunnel does not connect: try ssh user@host in a terminal first. Atlas uses the same keys and ~/.ssh/config.

Something else

  • A second server is refused for a home: one Atlas serves a home at a time, so two agents never write the same memory. Close the other app or the other atlas serve, or open another home.
  • A key that worked stops working after a restore: keys never travel in a backup. Store them again on the new machine.
  • The vault does not open: Atlas says why once, at start (no key, or the key of another vault), and runs without its secrets. A vault copied by hand from another machine needs that machine’s key, given as ATLAS_VAULT_KEY.

Still stuck? Search the issues on GitHub, or open one with what you did, what happened and the lines of the log around it. Remove anything private from them first.