문제 해결 가이드 (Troubleshooting)

Contexa CLI 설치, 프로젝트 초기화 및 런타임 구동 중에 발생하는 장애 요소를 스스로 복구할 수 있는 자가 해결 지침입니다.

Contexa Doctor 활용하기

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

Shell 
contexa doctor

진단기는 선택한 설치 경로에 필요한 항목만 확인합니다. 프로젝트를 변경하지 않고 사전 점검만 하려면 contexa init --check를 실행하고, 별도 상태 보고가 필요하면 contexa doctor를 사용합니다.

주요 장애 카탈로그 및 해결책

① Permission Denied (권한 오류)

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

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

해결 방법: 설치기는 /usr/local/bin에 쓸 수 없으면 자동으로 ~/.local/bin을 사용합니다. 설치 스크립트 자체를 sudo로 실행하지 말고 아래 명령을 다시 실행하세요.

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

설치 후 ~/.local/bin이 PATH에 없다면 셸 설정에 추가한 뒤 새 터미널에서 contexa --version을 확인합니다.

② Docker not running (도커 미기동)

로컬 Docker 인프라, 시뮬레이션, 분산 모드를 선택했는데 Docker 서비스가 비활성 상태일 때만 발생합니다.

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

해결 방법:

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

③ PostgreSQL / Ollama Port Conflict (포트 충돌)

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

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

해결 방법:

  • 기존 서비스 확인: 포트를 점유한 서비스가 의도한 PostgreSQL/Ollama인지 먼저 확인합니다. CLI가 임의로 종료하거나 설정을 바꾸지 않으므로, 재사용할 연결 정보는 사용자가 선택한 인프라 설정과 일치시켜야 합니다.
  • 격리 시뮬레이션 모드 사용: 기존 로컬 서비스와 충돌 없이 온전히 컨테이너를 띄우려면 simulate 모드로 초기화하십시오. 포트가 +20000 으로 격리 매핑되어 띄워집니다. 
    contexa init --simulate

④ Ollama Model Missing (AI 모델 유실)

AI provider로 Ollama를 선택했지만 필요한 모델 파일이 아직 런타임 환경에 내려받아지지 않은 경우에만 발생합니다.

에러 예시: 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 설정을 동기화하여 해결할 수 있습니다.

⑤ Starter만 추가했는데 Contexa 테이블이 없음

@EnableAISecurity가 없는 dependency-only 상태에서는 정상입니다. Starter 추가만으로 Contexa 필터, 인증 Provider 또는 IAM 스키마를 만들지 않습니다. OSS와 Enterprise의 테이블은 각 기능이 활성화된 서버 런타임이 기동될 때 해당 모듈의 책임으로 생성·검증합니다.

⑥ contexa reset이 일부 변경을 되돌리지 않음

reset은 설치 매니페스트에 기록된 CLI 소유 변경만 되돌립니다. 사용자가 원래 추가한 Starter나 설치 후 직접 수정한 파일은 임의로 삭제·덮어쓰지 않습니다. 충돌 보고가 나오면 파일과 매니페스트를 확인한 뒤 사용자 변경을 직접 정리하십시오. 확인만 하려면 contexa reset --simulate를 사용합니다.

⑦ ai.ctxa 의존성을 찾지 못함

정식 0.1.0 소비자는 mavenCentral()만 사용합니다. Spring milestone/snapshot 또는 Sonatype snapshot 저장소를 일반 사용자 빌드에 추가하지 마세요. 게시 직후라면 Maven Central 동기화가 끝난 뒤 다시 시도하고, 좌표가 ai.ctxa:spring-boot-starter-contexa:0.1.0인지 확인합니다.