Skip to content

Verification and troubleshooting

Run these checks after installation, in any scenario.

Health check

Open:

  • https://your.easy.host/ai/chain/sys/monitoring.json

Expected result: JSON with the current chain version.

Runtime info check

Open:

  • https://your.easy.host/ai/chain/api/info

This endpoint shows:

  • chain version
  • detected LLM providers
  • default LLM ID
  • embeddings provider and model
  • ChromaDB URL and detected version

Container checks

Run:

docker compose ps
docker compose logs chain
docker compose logs celery
docker compose logs chroma

In Basic scenarios chroma can be running, but Basic does not use it.

Common problems

401 Unauthorized from chain

Usually caused by:

  • different EASY_JWT_SECRET values in Easy8 and Chain
  • a missing Authorization: Bearer ... header on the request

Chain starts but AI features do not work

Usually caused by missing or unreachable LLM configuration:

  • no OPENAI_API_KEY
  • no AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT
  • no reachable LLM_URL

Also check the public URL. If EASY_AI_PUBLIC_URL is not set, Easy8 builds it from Host name and path in the Easy8 settings (/settings). After you clone production into a test instance, that setting can still point to the production host, and browser requests fail with 404. Open both URLs above on the host of the current environment. See After you clone an environment.

PRO and Helpdesk features fail

Usually caused by missing or unreachable retrieval infrastructure:

  • wrong CHROMADB_URL
  • unreachable EMBEDDINGS_URL
  • EMBEDDINGS_URL does not point to a TEI endpoint serving BAAI/bge-m3
  • LLM_URL does not point to a vLLM endpoint serving gemma-4-26b
  • vLLM exposes a deployment-specific model id without a matching VLLM_MODEL_ALIASES mapping
  • stopped celery service

Wrong ChromaDB port inside Docker

Inside Docker, use:

CHROMADB_URL=http://chroma:8000