Troubleshooting — Resolve Installation & Config Issues

Contexa Doctor 활용하기

Contexa는 JDK, 도커 데몬, 데이터베이스, AI 모델 등 여러 인프라가 엮여 작동합니다. 설치 중 오류가 발생하거나 동작이 의심스러울 때 아래 명령어로 로컬 환경을 전수 스캔하십시오.

Shell

contexa doctor

진단기가 상태를 분석하여 결함이 있는 항목에 대해 명확한 조치 명령어([FIX])를 제시합니다. 또한 contexa init --check 명령어를 사용해 설치를 시도하기 전에 미리 환경의 기동 적합성을 사전 테스트해 볼 수도 있습니다.

CLI 설치 시 시스템 공용 디렉토리(/usr/local/bin)에 실행 바이너리를 작성할 수 없을 때 발생합니다.

에러 예시: Permission denied to write /usr/local/bin/contexa

해결 방법:

권한 상승 설치: sudo 명령어를 사용해 설치 스크립트를 구동하십시오.
```
curl -fsSL https://install.ctxa.ai | sudo sh
```
사용자 홈 디렉토리 격리 설치: 권한 상승이 불가능한 경우 개인 바이너리 경로를 prefix로 전달하십시오.
```
curl -fsSL https://install.ctxa.ai | sh -s -- --prefix ~/.local/bin
```

초기화 작업 중 인프라 컨테이너를 가동하려 할 때 도커 엔진이 켜져 있지 않아 발생합니다.

에러 예시: Docker daemon is not running or unreachable.

해결 방법:

Windows / macOS: Docker Desktop 어플리케이션을 구동하고 우측 하단의 고래 아이콘이 정상 안착할 때까지 대기합니다.
Linux: 터미널에서 systemd 서비스를 기동합니다.
```
sudo systemctl start docker
```

Contexa 기본 인프라 포트(5432, 11434 등)가 기존에 설치된 호스트 프로그램이나 타 컨테이너에 의해 점유되어 충돌하는 현상입니다.

에러 예시: Port 5432 is already in use on 127.0.0.1. Skip creating postgres container.

해결 방법:

자동 우회 (호스트 인프라 재사용): Contexa CLI는 포트 충돌 감지 시 해당 컨테이너 기동을 안전하게 스킵하고 호스트에서 기동 중인 데이터베이스에 자동 연결을 시도하도록 설계되어 있습니다.
격리 시뮬레이션 모드 사용: 기존 로컬 서비스와 충돌 없이 온전히 컨테이너를 띄우려면 simulate 모드로 초기화하십시오. 포트가 +20000 으로 격리 매핑되어 띄워집니다.
```
contexa init --simulate
```

Ollama 런타임은 동작하지만 AI 보안 인가 판단 및 임베딩 분석을 위한 인공지능 가중치 모델이 다운로드되어 있지 않아 런타임 예외를 유발하는 현상입니다.

에러 예시: Model 'qwen2.5:7b' is missing on Ollama server.

해결 방법: 아래 명령어를 수행하여 필요한 AI 모델 리소스를 올라마 엔진에 직접 로딩(Pull)하십시오.

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

메모리가 부족한 저사양 머신의 경우 환경 변수(OLLAMA_CHAT_MODEL)를 지정해 경량 대체 모델(예: qwen2.5:3b 또는 1.5b)을 풀링하고 application.yml 설정을 동기화하여 해결할 수 있습니다.