Skip to content

Verification And Troubleshooting

Use these checks after installation for any on-premises 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

For Basic scenarios, chroma may be present in the package but is not required by the product.

Customer handover checklist

Before handing the installation over to the customer, confirm:

  • EASY_JWT_SECRET is configured and shared correctly
  • the selected scenario page matches the deployed product and hosting mode
  • Nginx publishes /ai/chain
  • https://your.easy.host/ai/chain/sys/monitoring.json works
  • https://your.easy.host/ai/chain/api/info shows the expected providers
  • all required containers for the selected scenario are running
  • the selected LLM provider is reachable from chain
  • for Pro scenarios, Chroma and embeddings are reachable from chain

Common problems

401 Unauthorized from chain

Usually caused by:

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

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
  • no reachable LLM_URL

Also check the public Easy8 URL configuration:

  • if EASY_AI_PUBLIC_URL is not set, Easy8 defaults it from Host name and path on /settings
  • this uses the main Easy8 application URL built from ::Setting.protocol and ::Setting.host_name
  • after cloning production to a test instance, this setting may still point to the production host
  • browser requests can then go to the wrong /ai/chain URL and fail with 404 if that host does not publish the chain reverse proxy for the tested environment
  • verify that https://your.easy.host/ai/chain/sys/monitoring.json and https://your.easy.host/ai/chain/api/info work on the actual host used by the current environment

Pro 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
  • stopped celery service

Wrong ChromaDB port inside Docker

For Docker internal communication, use:

CHROMADB_URL=http://chroma:8000