Atomic Agent

Atomic Agent: Fixes

This page covers the problems people hit most often with Atomic Agent, each in the order symptom, likely cause, and fix. It comes after Nine jobs to try, but you can jump here from any page when something goes wrong.

These fixes come from the official docs, the release notes, and frequent GitHub issues, checked on 14 November 2026 against v0.7.0 and the desktop app 0.0.8. If something goes wrong that is not listed here, the main guide's troubleshooting page has general help.

Common problems

The install fails

Symptom: the Mac terminal installer stops with "no published build for darwin-x64," a terminal update fails with "install script exited with code 1," or PowerShell says it does not recognize atomic-agent after the install.

Likely cause: the first message means an Intel Mac, which has no build at all. The update failure was traced in GitHub issue #53 to releases that had not been published yet, so the updater had nothing to download. A command that is not found means the terminal has not picked up the folder the installer added to your PATH, which on Windows is %LOCALAPPDATA%\atomic-agent by default.

Fix: on an Intel Mac, stop and go back to the main guide, because building from source is not a beginner job. For a failed update, wait a while and run atomic-agent update again, or paste the original install command from Install and first job again. For a command that is not found, open a new PowerShell or Terminal window and type atomic-agent --help again.

The model gives errors

Symptom: a reply fails with words such as "Key rejected," "Could not check this key," "rate-limited," a billing message, or a note that a provider is not signed in.

Likely cause: one of three things. The key is wrong or was pasted with a missing character, the provider is limiting how fast you can send requests or your free tier ran out, or the model name or provider entry does not match what the provider offers.

Fix:

The local model will not answer

Symptom: the desktop app says the local model is not answering or not running, or the terminal version does nothing after you send a message.

Likely cause: the model server is not running, no model is selected, the model is too big for your computer's memory, or, in desktop 0.0.3, a key mix-up that GitHub issue #686 says was fixed in desktop 0.0.8.

Fix: in the desktop app, use the Start model button if it appears, and run the Doctor in Settings › Diagnostics, which checks the engine, port, model, memory, and keys and fixes what it can. In the terminal, check the server first:

atomic-agent models status

If it does not say ok, start it with atomic-agent models start. If no model is selected, run atomic-agent models pull qwen-3.5-4b and then atomic-agent models use qwen-3.5-4b. If it says the model will not fit, pick a smaller one from atomic-agent models list, or run atomic-agent models devices to check that the right graphics chip was picked. The release notes for desktop 0.0.5 say local models run on the CPU on Windows PCs with an ARM chip, so expect them to be slow there.

The agent loops or repeats itself

Symptom: the agent runs the same step again and again, fires off search after search without getting closer, or ends a long turn with max_steps instead of an answer.

Likely cause: usually a small local model with a vague request. The tips page says frequent loops on one task are a sign the request is underspecified, and an open GitHub issue, #602, describes a local model on Windows looping on a file-sorting job.

Fix: the agent has a loop detector that warns it, then blocks the repeated step, and then ends the turn with a plain reply, so it usually recovers on its own. If it keeps happening, stop the run, then send a smaller request with one goal, one folder path, and a clear finish line. If you use a small local model, try the same job with Gemini, or run atomic-agent models recommend to see whether a bigger local model fits your computer.

You need to stop it right now

Symptom: the agent is doing something you did not ask for, or you simply want it to stop.

Likely cause: none needed. Stop first and work out why later.

Fix:

Afterward, open the folder yourself and look in the Trash or Recycle Bin for anything the agent moved there. If it already changed something, read After it does something wrong.

The browser will not open

Symptom: the agent says it cannot use the browser, or browsing jobs fail while web search still works.

Likely cause: Atomic Agent does not include a browser, so it needs Chrome, Edge, or Chromium already installed, and it looks for Chrome unless told otherwise.

Fix: install Chrome, or tell the agent to use Edge or Chromium by adding the line ATOMIC_AGENT_BROWSER_CHANNEL=msedge (or chromium) to the .env file in your .atomic-agent folder, then restart Atomic Agent. That file also holds your keys, so do not share it. This guide could not confirm whether Edge is picked automatically when Chrome is missing.

A setting you changed does nothing

Symptom: you changed a setting in config.json or .env, but the agent behaves the same.

Likely cause: the troubleshooting page says settings are read once when the agent starts, and secrets in .env are picked up after a restart.

Fix: quit Atomic Agent completely and open it again. The CLI reference says changes made in the terminal version's own panels apply right away, so those do not need a restart.

A scheduled job stopped running

Symptom: a daily job ran for a while, then nothing arrived.

Likely cause: the scheduling page says a repeating job that runs out of retries, or hits an error it treats as permanent, stops for good and silently. A job also cannot run while Atomic Agent is closed, and runs missed while it was closed happen only once.

Fix: run atomic-agent task list to find the job, then atomic-agent task show followed by its id to read the error. Fix the cause, then set the job up again, because a stopped job cannot be restarted. Add --notify telegram to any job you depend on, so a failure reaches your phone.

Update it safely

Symptom: you want a newer Atomic Agent, and you want your chats and settings to survive the change.

Likely cause: none needed. Updating is a choice, and the copy comes before the new version.

Fix:

  1. Quit the desktop app and any terminal session that is still running Atomic Agent. Copy the whole .atomic-agent folder from your home folder, which is %USERPROFILE%\.atomic-agent on Windows and ~/.atomic-agent on a Mac. That folder holds config.json, .env, sessions.sqlite, memory.sqlite, tasks.sqlite, skills, models, and traces. Also copy the work folder you gave the agent, such as atomic-tryout inside Documents. A copy of either folder can live in Windows File History or Previous Versions, or in Mac Time Machine. The program can write its own archive if you run atomic-agent data backup and a file name ending in .tar.gz, saved in Documents and not inside .atomic-agent. Keep that archive private, because it holds your API keys, while leaving out models (unless you add --with-models) and the browser profile.

What you should see a second copy of .atomic-agent and of your work folder, stored outside both folders.

  1. Read the release notes on the project's releases page before you install anything. For the terminal version, run atomic-agent update, or confirm the update prompt in the text screen, then reopen Atomic Agent so the new version starts. If you use Atomic Agent's own local model rather than only a cloud key or Ollama, also run atomic-agent models update to update its model engine (that command refuses when no managed local model is set up). In the desktop app on Windows, or on a Mac once the app is in Applications, the desktop 0.0.1 release notes say the app checks for new versions when it opens and every 6 hours, then asks before downloading or installing anything. If no prompt appears, download the new installer from the download page and run it. This guide could not confirm that a past update reset a saved setting, or whether the desktop installer ever touches .atomic-agent, which is why step 1 comes first.

What you should see the update ends with no error, and Atomic Agent still opens.

  1. Run atomic-agent --version if you installed the terminal version, or reopen the desktop app and check that it starts cleanly. Then ask the agent to list the files in your tryout folder and to change nothing.

What you should see a version number (in the terminal), then a short file list, and no approval card for a write or a delete.

Automatic update checks.

You want to uninstall or start over

Symptom: you want Atomic Agent gone, or you want a clean start.

Likely cause: none needed. Pick how much you want to remove first, because the full uninstall has no undo.

Fix:

After an uninstall, delete the keys you made for Atomic Agent on each provider's website and in @BotFather, because the uninstall removes only the copies on your computer.

If you are still stuck

In the terminal text screen, /dump saves a zip file in atomic-agent-debug inside your Documents folder, and /report can attach it to a GitHub issue after you confirm. The troubleshooting page warns that the zip holds your chats, prompts, and file paths, so open it and remove anything private before you post it.

You can also ask on the project's GitHub issues page or its Discord, which the README links.

Sources

Checked 14 November 2026.

Next

Next: Advanced features.

Checked 14 November 2026 · prices, limits, and versions change