Help
Troubleshooting
Fixes for installing, starting, connecting a model and running tasks with AlbertCode SWE Agent and mini-AlbertCode SWE Agent.
Commands below use albertcode; for mini-AlbertCode, use albert-mini. If none of these fit, open an issue.
Installing
| Symptom | Fix |
|---|---|
command not found right after installing |
Open a new terminal. The installer added the command to your PATH, and only new terminals see it |
| macOS: "Apple could not verify…" or "unidentified developer" | The installers aren't signed yet. Open System Settings → Privacy & Security, click Open Anyway, then open the installer again — or use the one-line command |
| macOS: "could not be executed because you do not have appropriate access privileges" | The browser saved the installer without permission to run. Download the .zip for your Mac instead, or run the .command file with bash in Terminal |
| Windows: "Windows protected your PC" | Choose More info → Run anyway, after checking the checksum |
| Windows: PowerShell refuses to run the command | Your organisation may block scripts. Download the .cmd installer from the release and double-click it |
| Windows: the old files are in use, or "Access is denied (os error 5)" | The agent was still open somewhere. Close every terminal (and VS Code window) using it, or run albertcode stop, then run the installer again |
Linux: the installer refuses to run under sudo |
Run it as yourself. It installs for your user and asks for your password only when it needs to |
| Linux: "no installer for Linux on … processors" | Only x86-64 is supported for now, not ARM |
| Linux: the install fails on Alpine or another musl system | Not supported: use a glibc distribution such as Ubuntu, Debian or Fedora |
| pypi.org can't be reached | Check your connection. Behind a proxy, set HTTPS_PROXY and run the command again |
invalid peer certificate or UnknownIssuer |
Your network inspects encrypted traffic. Current installers retry with your computer's certificates; if that fails, set UV_NATIVE_TLS=1 and run again |
| "the package inside it is damaged" | The download was cut short or altered. Download it again |
Every installer run writes a log — see Installation for where.
Starting and connecting
| Symptom | Fix |
|---|---|
"No model is connected" / No model connected yet. |
Run /connect, or Connect a provider in the browser |
| After updating, your model is no longer connected | A new version can clear saved keys the first time it starts. Run /connect again |
A provider shows key not accepted |
The provider refused the key. Connect again with a new one |
A local server shows not answering |
Start your model server, then check its address with /connect |
| A model connects but tasks stall, or it never changes anything | It may not support tool calling well. Run albertcode models test |
Waiting for the service at http://127.0.0.1:8778 … (mini) |
It is starting. If it keeps waiting, run albert-mini doctor, then albert-mini stop and try again |
| The browser page says to open the agent from your terminal | Run albertcode web (or albert-mini web). It signs your browser in |
| VS Code can't reach AlbertCode | Run albertcode once in a terminal to start the service, then reload the VS Code window |
Running tasks
| Symptom | Fix |
|---|---|
| Tests don't run, or use the wrong tool | Run albertcode doctor to see which build tools AlbertCode finds, then install or add the missing one to your PATH |
| Accepting a change is refused | You edited a file the change also touches. Look at your edits, then run the task again |
| A change is waiting and nothing happens | It is at a gate: answer it in either interface. albert-mini -c reopens the latest session in a folder |
A scripted run exits with code 3 |
It stopped at a gate --approve didn't cover. Open the session and answer it |
| A run stopped saying it was going in circles | It repeated the same steps with the same answers several rounds running, so it was stopped before spending more on the model. Ask again naming what is still missing, or ask for a smaller piece |
| Every step says Waiting for the model for a long time | Each step is one request to your model. Try a faster model, or AlbertCode's fast pace, which skips the two reviews |
| Everything seems stuck | Run albertcode stop, then albertcode again |
| Anything else (mini) | albert-mini doctor checks the installation and the service, and says what to do |
Reporting a problem
Open an issue on albertcode-swe-agent or mini-albertcode-swe-agent with what you ran, what you expected and what happened, plus --version and your operating system.
The full troubleshooting guides are in each repository: AlbertCode SWE Agent · mini-AlbertCode.
A guide written for this site, covering both agents. For every command and setting, see the full reference for AlbertCode SWE Agent and mini-AlbertCode.