Troubleshooting

This page lists the problems people run into most often, what you see when they happen, and how to fix them. If your problem isn’t here, see Reporting a problem at the end.

Providers

Claude Code session expired or API key invalid

What you see: a message with a 🔑 icon in the project chat saying the Claude Code session has expired (or the key was rejected), the whole team is paused, and agents show an error state.

Fix:

1. Sign in again in a terminal. You can use Terminal → Shells inside Agentbits.

   claude auth login    # for Codex CLI: codex login

2. Open Settings → Providers and test the provider again. For Claude Code this checks claude auth status.

3. Click Resume in the top bar. This clears the error states and starts the team again.

For the Anthropic API or OpenAI API, enter the key again: delete the provider in Settings → Providers and add it again with the new key.

CLI not found

Agentbits does not include or install Claude Code or Codex CLI. It looks for them on your PATH. In Settings → Providers → Add provider, the form shows ● installed or ○ not found.

If you see ○ not found:

1. Install the CLI and sign in once (claude auth login or codex login).
2. If it is installed in a folder that isn’t on PATH, enter its full path in CLI path (empty = find on PATH).
3. Save and test the provider again.

Projects and folders

“No folder selected”: CLI agents won’t run

Claude Code and Codex CLI agents work inside the project’s folder. A project without a folder shows an amber No folder selected chip in the section bar, and CLI tasks in it are refused. The Permission Matrix shows “no folder selected — CLI agents won’t run”.

Fix: double-click the project tab (or use the project settings button next to the folder chip), choose a Folder and save. Demo and API providers don’t need a folder.

Warning: CLI agents really change files in that folder. Start with an empty folder or a git branch.

The folder is rejected

When you choose a folder, Agentbits checks it and explains why it can’t be used:

Message	What to do
“This folder is the Agentbits app itself…”	Pick another folder. Agents must not change the app’s own code.
“This folder is already used by the project …”	Each folder belongs to one project. Open that project, or pick another folder.
“This folder is too broad for agents…”	A drive root, your home folder or a folder that holds Agentbits’ data can’t be used. Pick the project’s own folder.
“folder not found” (in the project picker)	The folder was moved or renamed. Choose its new location in the project settings.

Agents don’t start working

If tasks sit in To do or nothing moves, check these in order:

• Approval cards. Agents with Require approval on wait for you. Agents created from templates start with it on. Approve the card in the left panel.
• Pause all. If the top bar shows Resume, everything is paused. Paused stays paused after a restart.
• Autopilot. Without it, idle agents don’t pick up tasks on their own. Turn it on in Settings → General, or start tasks yourself.
• Held tasks. A task you rejected or stopped, one that failed twice, or one interrupted by closing the app is not picked up again automatically. Start it by hand or move it back to To do.
• No lead. Without a lead the chat can’t turn your message into tasks. Pick one in Organization → Teams or in the project settings.
• Codex CLI. A Codex agent with Read files turned off doesn’t run.

App window and data

“Couldn’t load data” and Try again

If the app opens to a Couldn’t load data screen, click Try again. If it keeps failing:

• Did you go back to an older version? A database upgraded by a newer version can’t be opened by an older one. Install the newer version again.
• To check whether the problem is your data, start once with an empty data folder using AGENTBITS_DATA_DIR (see Install). This doesn’t touch your real data.
• To go back to a backup by hand, close the app, copy a file from the backups folder into the data folder as agentbits.db, and delete agentbits.db-wal and agentbits.db-shm next to it. Copy the current files somewhere safe first.

If only one section shows This view ran into an error, click Try again or switch to another section. The rest of the window keeps working.

Pipe mode badge in Shells

If Terminal → Shells shows Pipe mode · interactive programs are not supported, the real terminal component couldn’t be loaded. Shells still run commands, but full-screen programs, password prompts and arrow keys don’t work, and Ctrl+C only clears the typed line. Agent terminals are not affected.

When running from source, run npm install again. Don’t use --no-optional or --omit=optional, and don’t run electron-rebuild.

SmartScreen warning when installing

There is no published installer yet. When installers are published, or if you build one yourself, they are not code-signed, so Windows shows “Windows protected your PC”. Click More info, then Run anyway.

The macOS package hasn’t been tested on a real Mac yet. If you build one, macOS warns on first launch because it isn’t notarized: open System Settings → Privacy & Security and choose Open Anyway.

Running from source

Black window, ERR_CONNECTION_TIMED_OUT

The window stays black and the terminal shows ERR_CONNECTION_TIMED_OUT for localhost:5173: the app can’t reach the development server. It retries several times and then shows a troubleshooting page.

1. Stop and start npm run dev again.

2. In a separate PowerShell window, check that the server answers: curl.exe -I http://127.0.0.1:5173.

3. Make sure your antivirus or firewall isn’t blocking Node.js.

4. As a workaround, build and run the app without the development server:

   npm run build
   npm start

“Electron failed to install correctly”

The Electron download was probably interrupted during npm install. Run its installer again:

node node_modules\electron\install.js

If the download is blocked or slow, use a mirror:

$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
node node_modules\electron\install.js

Afterwards node_modules\electron\dist\electron.exe should exist.

PowerShell: “running scripts is disabled on this system”

PowerShell’s execution policy can block the npm and npx scripts. Allow local scripts for your user, or call npm.cmd directly:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# or, without changing the policy:
npm.cmd run dev

This doesn’t affect the app’s own Shells.

Database module error after updating

If you see a better-sqlite3 module error, don’t run electron-rebuild. Delete node_modules, run npm install again and make sure you use Node.js 22 or newer.

Reporting a problem

Open an issue on GitHub with your operating system, the Agentbits version (shown in Settings → General), the provider you used and the steps that lead to the problem. Remove API keys, paths and personal data from screenshots. You can also use the Feedback button in the status bar, which opens a prepared email.

Security problems should not go into a public issue. Report them privately as described in Security.