Troubleshooting

Self-healing guidelines for diagnosing and resolving installation, initialization, and runtime environment issues with Contexa CLI.

Diagnosing with Contexa Doctor

Contexa always requires a JDK runtime. Database, Docker, and LLM checks depend on the features you selected in the installer. If you hit any issue during installation, scan your environment using the doctor command:

Shell 
contexa doctor

Diagnostics check only what the selected installation path needs. Run contexa init --check to perform preflight checks and exit without changing the project, or use contexa doctor for a separate status report.

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: the installer automatically falls back to ~/.local/bin when /usr/local/bin is not writable. Do not run the installer script itself with sudo; run the command below again.

curl -fsSL https://install.ctxa.ai/install.sh | sh

If ~/.local/bin is not on PATH, add it to your shell profile, open a new terminal, and run contexa --version.

② Docker not running

Occurs only when you selected local Docker-managed infrastructure, simulation, or distributed mode and 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:

  • Inspect the existing service: Verify that the process holding the port is the intended PostgreSQL or Ollama instance. The CLI does not terminate it or rewrite settings arbitrarily; make the reused connection details match the infrastructure path you selected.
  • 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

Occurs only when you selected Ollama as the AI provider and the required 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.

⑤ No Contexa tables after adding only the Starter

This is expected in dependency-only state without @EnableAISecurity. Adding the Starter alone does not create Contexa filters, authentication providers, or the IAM schema. OSS and Enterprise tables are created and validated by the corresponding activated server runtime.

⑥ contexa reset does not revert every change

reset reverts only CLI-owned changes recorded in the installation manifest. It does not arbitrarily delete a Starter dependency that the user already owned or overwrite files edited after installation. If a conflict is reported, inspect the file and manifest, then resolve the user-owned change explicitly. Use contexa reset --simulate for a dry run.

⑦ Maven cannot resolve an ai.ctxa dependency

Stable 0.1.0 consumers need only mavenCentral(). Do not add Spring milestone/snapshot or Sonatype snapshot repositories to a normal consumer build. Immediately after publication, wait for Maven Central synchronization, then verify the coordinate is ai.ctxa:spring-boot-starter-contexa:0.1.0.