9. Help

9.1 When something goes wrong

On a new PC, “Kit health” first. Then the most common problems, the message you see and what to do: downloads, ports in use, servers that won't start, expired sign-ins. And how to report a problem with the diagnostics zip.

In short

  • Search for the message you see in the box below: the guide collects the most common ones, with the remedy.
  • Almost every error has a tooltip on mouse-over and a line of output or log that tells you more.
  • The app's log is in data\app\logs\app.log; the servers' logs are next to it.

Kit health

On a new PC, or with the kit on another stick, look first at Settings › “The kit” › “Kit health”: one line per check, green when fine, yellow for a warning, red for an error, and under it what to do. “Check again” runs the checks again after a fix.

  • The drive. FAT32 holds files up to 4 GB (no large local models or database copies) and no links: for a kit on a stick exFAT is better, or NTFS if it stays on Windows. On macOS and Linux a drive mounted noexec (or FAT32 with showexec on Linux) lets no program start: the line gives the command to remount it.
  • The free space: under 5 GB a warning, under 1 GB an error (installs, downloads and database copies fail). Free up space or move the kit to a larger drive.
  • The kit's path: &, %, !, ^, quotes and accented or non-Latin letters confuse cmd, PowerShell, Maven and Gradle. Move the kit to a folder with only letters, digits, hyphens and spaces.
  • Files made private by another account, often on another PC: the kit cannot read them (settings, keys, the agents' sign-ins). The line gives the command to take them back, to run in an administrator terminal: takeown and icacls on Windows, sudo chown on macOS and Linux. The app does not run it itself because it needs administrator rights.
  • On Linux, the system's libraries: libaio and libnuma for MySQL, libicu for .NET, libvulkan1 for the graphics card of the local models (without it they stay on the CPU). The line gives the command to install them, for example with apt.
  • From the command line .\Atollo.exe check --kit | Out-Host runs the same checks, and ends with 1 if one is an error.

Download and installation

A component stays in “error” with “failed” and a network or certificate message.

Often it is the network: a company proxy or HTTPS inspection. Fill in Settings › Network and try again. If that is not enough, use the “Download it in the browser” panel under the row and hand the file to the kit.

Learn more: Company network: proxy, certificates, local network (6.3)

“in use: close the kit programs and try again”

A kit program (a running project, a console, the editor, a database) is using the files to be replaced. Stop it, close the consoles and try again. If you do not know what is open, the “Remove drive” page lists it.

Learn more: Safely removing the drive (7.1)

“An installation is already running.” or “An installation is already in progress”

Wait for it to finish (the status bar shows the step) or press “Cancel” in the “Apply” bar.

A component is “to update” (yellow triangle).

On macOS and Linux, after the kit is moved, some components must be reinstalled: the kit does it by itself at start. If it stays that way, press “Update all” at the bottom of the Tools page.

Learn more: On another PC, another letter, another folder (7.2)

A program crashes or a library is missing, with the kit on a USB stick.

One of the program's files may be damaged on the stick. Press “Check the files” on the Tools page (or run check --files): it lists the folders with files missing or changed since the installation, and “Reinstall” puts them back at the same version, without touching projects and databases.

Learn more: The Tools page (5.1)

Projects and sites

“Port already assigned to …”, “Port … already belongs to server/database/project …: choose another one.”, “Ports 7000 to 7099 belong to the editor” or a program saying the port is taken.

A port belongs to one thing only: an action of a project, a pool of the Web Servers page, a version of a database or the editor (7000-7099). The message says who already has it: “Port already assigned to …” another action, “already belongs to server …” a pool, “already belongs to database …” a version of MySQL or MongoDB, “already belongs to project …” an action. It applies to the port of an action, of a pool and of a database version. If instead a program on the PC has the port, that program says so. For an action, empty the “Port” field to go back to the automatic port; otherwise choose another one between 1024 and 65535.

Learn more: Starting a project: actions and ports (2.3)

An action stops at once with “error (code 1)”.

Read the last lines of the output: they usually say what is missing. Common cases: dependencies not installed (run npm install or composer install first), a missing component (“Components” section › “Install what is missing”), a wrong version (“Versions” section).

Learn more: Components and versions of a project (2.4)

“Action not found: press Refresh”

The project has changed (for example panel.json). Press “Refresh” on the project page.

“panel.json is not valid JSON: ignored.”

There is a syntax error in the file (an extra comma, a missing quote). Fix it in the editor and press “Refresh”.

Learn more: Starting a project: actions and ports (2.3)

“The shared server … did not start: see the Web Servers page.”

Open the Web Servers page, choose the pool and look at the error. Often the port is taken: change the profile's port, or choose “Its own server” in the project's “Website” section.

Learn more: Websites and .localhost addresses (3.3)

The site opens but shows old files or a blank page.

Check the folder in “Folder to serve as a website” (for many PHP frameworks it is public) and reload the browser page bypassing the cache (Ctrl+F5).

The editor does not notice changed files.

On Windows this happens if a folder in the kit's path starts with a digit, with x or with u: the app flags it with a warning. Move the kit to a different path.

Learn more: The first start (1.2)

Databases

“Port … is already used by another program: change it below.”

Another MySQL or MongoDB (installed separately) runs on the PC on the same port. Change the “Port” on the server page (for example 3307) and start it again; then rewrite the connection in the projects' .env with “Write to .env”.

Learn more: The database servers (3.1)

The server stays in “Error” after starting.

The server page shows the last error and the path of the log (data\app\logs). On Linux MySQL may ask for the libaio and libnuma libraries: the message gives the command to install them.

The project does not connect to the database.

Check that the server is “Running”, then use “Write to .env” in the project's “Databases” section: the .env will have the right user, password and port. If the project uses another version of the server, the port is different (3307…).

Learn more: A project's database (3.2)

Agents, Git and GitHub

“sign-in expired” in the agents.

Open the agent in a project: it renews the sign-in, or has you sign in again.

Learn more: The agents: Claude Code, Codex, Antigravity, Pi (4.1)

Git says “Please tell me who you are” at the first commit.

Type your name and email in Settings › “GitHub account” › “Who signs the commits”, or sign in to GitHub: if they are empty, the account fills them. In a kit terminal git config --global user.name and user.email work too.

Learn more: The kit's GitHub account (6.1)

“GitHub refused the sign-in: sign in again.”

The token is no longer valid (revoked or expired). In Settings › “GitHub account” press “Sign out” and then “Sign in to GitHub”.

Learn more: The kit's GitHub account (6.1)

App start

“The kit's disk is read-only: cannot write to the folder …”

The USB stick is write-protected (sometimes there is a switch) or mounted read-only. The kit must be able to write in its folder.

macOS: “macOS opened Atollo from a temporary read-only copy (App Translocation)”.

It happens with downloaded apps that are not notarized. The message shows an xattr command: run it in Terminal and reopen Atollo.

Learn more: On another PC, another letter, another folder (7.2)

Linux: the disk is mounted with noexec, or WebKitGTK is missing.

The message explains what to do: remount the disk with execute permission, or install the packages it names.

Windows: WebView2 is missing.

WebView2 is the Windows component that draws the window; it is already in Windows 11 and almost always in Windows 10. If it is missing, Atollo shows the link to install it.

Warning: “Programs from another copy of the kit are open on this PC”.

Just information: another kit is open. The two copies share nothing.

If the problem is not here

  • Read the action's output (“Run” section) or the server's log: the last line usually gives the cause.
  • Close Atollo and open it again: many things (environment, agents, kit files) are regenerated at every start.
  • Check the components with “Verify” on the Tools page, or with .\Atollo.exe check | Out-Host.
  • If it still does not work, report it: the section below says how.

Reporting a problem

In Settings › “The kit” › “Reporting a problem” there are two buttons, to use in this order.

  • “Export diagnostics” makes the zip atollo-diagnostica-<date-time>.zip on the PC in data\app\diagnostics: version and system, the kit's disk (file system, kind, free space), RAM, the kit's environment, the programs' check, the components, the ports and the end of every log. “Open folder” shows it. From the command line .\Atollo.exe diagnostics | Out-Host does the same.
  • Before the zip is written, every secret the kit keeps (the keys of data\app\secrets, Claude Code's token, the database passwords, the agents' sign-ins, the GitHub token) becomes *** wherever it appears; your profile folder becomes ~, your user name and the PC's name ***. Open it and look at it anyway before attaching it: a project can write things into the logs that the kit does not know.
  • “Report a problem” opens a new issue on github.com/nabre/atollo in the browser with the bug form: Atollo's version and the system (kit, Windows build, the disk's file system and kind) are already filled in. Tell what happened and the steps to reproduce it, and drag the zip into the issue.
  • The app sends nothing: the zip stays on the PC until you attach it, and the issue reaches GitHub only when you press “Create” (a GitHub account is needed). From then on GitHub's privacy rules apply, and the issue is public.