Troubleshooting

🇧🇷 Portuguese UI The current product interface is in Portuguese.

Recovery path

The public runtime is explicit about failure. These are the first commands and checks the current release expects operators to use.

The official public path is still installer-first. Most users do not need a cloned repo. The manual aion-ctrl package path is only for recovery, verification, or advanced operational use.

First commands

Start here

If the installer already prepared the runtime, start with the packaged runtime engine under ~/.aion/bin/aion-ctrl-package/.

~/.aion/bin/aion-ctrl-package/aion-ctrl-linux-amd64/aion-ctrl status ~/.aion/bin/aion-ctrl-package/aion-ctrl-linux-amd64/aion-ctrl doctor ~/.aion/bin/aion-ctrl-package/aion-ctrl-linux-amd64/aion-ctrl repair ~/.aion/bin/aion-ctrl-package/aion-ctrl-linux-amd64/aion-ctrl backup

Common causes

What usually blocks the installer

Docker daemon not reachable
Docker Compose v2 missing
Default runtime ports already occupied
Insufficient disk or memory for the local runtime
Missing remote LLM credentials for the selected profile
Choosing local Ollama without intentionally preparing the machine for that profile

Preflight

Before install or play

Docker

Confirm the daemon is running and the current user can reach it.

Compose

Use Docker Compose v2. The public installer does not install it for you.

Ports

Free the default runtime ports or adjust the runtime environment intentionally.

LLM profile

Remote profiles are the default public path and need the expected API credentials before play succeeds. Local Ollama is optional.

Verify first

Run the basic host checks

Terminal

docker info
docker compose version
free -h
df -h

Remote OpenAI and Groq installs do not need Ollama. Only check ollama --version when you intentionally want the local Ollama profile.

Official links

Install or create what is missing

Docker Engine for Linux
Docker Compose plugin
Docker post-install permissions
OpenAI API key guide
Groq API keys
Ollama on Linux for the advanced local profile only

If Docker is healthy but the installer now stops on remote-provider readiness, double-check whether the API key itself was rejected. A valid-looking key string is not enough if the provider returns unauthorized or forbidden.

Support boundary

What this release supports

Linux x86_64 only
Ubuntu 24.04 / 22.04 and Debian 12 as the current target distros
Default runtime home: ~/.aion
--home /path changes runtime files, not side-by-side Docker isolation
Launcher shell plus web product surface after install, not a native installer
Do not run the public installer with sudo

Permissions

If the installer says `permission denied` for `~/.aion/distribution/.env`

This usually means a previous run created or preserved runtime files under ~/.aion with the wrong owner, often after running the installer with sudo.

Repair ownership

sudo chown -R $USER:$USER ~/.aion

After that, rerun the installer without sudo.

Reset path

Clean reinstall

If you do not need to keep the local runtime state, removing ~/.aion and running the installer again is also a valid recovery path.

This resets runtime files, but it does not make the current beta suitable for side-by-side installs on the same host. The runtime still uses fixed container names and default ports.

Docker access

If `docker info` fails with socket permission errors

Docker may be installed, but the current Linux user still cannot reach /var/run/docker.sock.

Follow the Docker Linux post-install permissions guide
Add the current user to the docker group
Log out and back in before rerunning the installer

Compose v2

If Docker works but `docker compose version` fails

The public installer requires Docker Compose v2. Install the Compose plugin, confirm docker compose version works, then rerun the installer.