Troubleshooting — Resolve Installation & Config Issues

Diagnosing with Contexa Doctor

Contexa relies on a combination of a JDK runtime, a Docker daemon, a database, and local/cloud LLMs. If you hit any issues during installation, scan your environment using the doctor command:

Shell

contexa doctor

The diagnostic utility will analyze your system and provide clear action steps (labeled [FIX]) for any failing component. You can also run contexa init --check to perform a pre-flight environment test before running the full setup process.

Common Issues and Fixes

① Permission Denied

Occurs when the installer script does not have write access to system binary directories (such as /usr/local/bin).

Error snippet: Permission denied to write /usr/local/bin/contexa

Resolution:

Elevated Privilege: Run the installer using sudo:
```
curl -fsSL https://install.ctxa.ai | sudo sh
```
User-local Installation: Avoid sudo by installing to a personal home bin path:
```
curl -fsSL https://install.ctxa.ai | sh -s -- --prefix ~/.local/bin
```

② Docker not running

Occurs when the CLI tries to deploy local database containers but the Docker service is inactive.

Error snippet: Docker daemon is not running or unreachable.

Resolution:

Windows / macOS: Launch Docker Desktop and wait for the status icon to turn green.
Linux: Start the systemd daemon:
```
sudo systemctl start docker
```

③ PostgreSQL / Ollama Port Conflict

Happens when standard infrastructure ports (5432, 11434, etc.) are already bound by another database instance or container on your host machine.

Error snippet: Port 5432 is already in use on 127.0.0.1. Skip creating postgres container.

Resolution:

Automatic Reuse (Default): Contexa CLI detects the bound port, skips creating a duplicate Postgres container, and configures the application to connect to the pre-existing host instance automatically.
Isolated Simulation Mode: If you want to spin up isolated containers side-by-side with your existing stack, use the simulation installer. Ports are automatically shifted by +20000:
```
contexa init --simulate
```

④ Ollama Model Missing

The Ollama server is running, but the required chat model files have not yet been pulled into the runtime environment.

Error snippet: Model 'qwen2.5:7b' is missing on Ollama server.

Resolution: Manually pull the missing model assets using docker command:

docker exec -it contexa-ollama ollama pull qwen2.5:7b
docker exec -it contexa-ollama ollama pull mxbai-embed-large

For low-spec or memory-limited environments, you can define the environment variable OLLAMA_CHAT_MODEL as a smaller variant (e.g. qwen2.5:3b or 1.5b) and synchronize it with your application.yml configurations.