openagentics
Docs Reference

Troubleshooting

The eight failure modes you're most likely to hit on a first deploy — symptom, cause, fix.

This page lists the failure modes you are most likely to encounter on a first deploy. Each entry follows a symptom, cause, and fix format. For the install steps themselves, see Docker Compose and Kubernetes.

Note: OpenAgentics v1.0 ships nine first-party MCP servers. The Docker Compose defaults enable all nine (web, admin, aws, azure, gcp, kubernetes, github, prometheus, loki) via the per-server OpenAgentic_<NAME>_MCP_DISABLED flags — though the cloud servers (aws, azure, gcp) and github only become usable once you supply credentials, and loki needs LOKI_URL set. The interactive setup wizard pre-selects the credential-free set (web, admin, kubernetes) plus the cloud servers and lets you toggle the rest. Enabled servers spawn, initialize, and register their tools at startup. During chat, the model calls those tools mid-turn through the agent loop. By default, mutating tool calls wait on the server-side approval gate (APPROVAL_GATE_MUTATING=true) before they execute, so a tool call that pauses for approval is expected behavior, not a misconfiguration. Auditing of every tool call is always on and is not gated by a flag.

API fails to start with “Cannot connect to Milvus”

Symptom. The API exits during boot. The logs show Cannot connect to Milvus after 10 attempts — shutting down.

Cause. This only happens when Milvus is enabled (MILVUS_ENABLED=true and SKIP_TOOL_SEMANTIC_CACHE=false) but unreachable. When enabled, the API connects to Milvus on boot and exits after its retry budget rather than degrading silently. A common trip-up: you set MILVUS_ENABLED=true but ran a bare docker compose up -d without the milvus profile, so the Milvus containers never started.

Fix. If you want Milvus, bring up the milvus profile so the containers exist:

Terminal window
docker compose --profile milvus up -d

This starts the standalone trio (etcd, minio, and milvus). Confirm that the API can reach Milvus on port 19530. On Kubernetes (where milvus.enabled: true by default), verify the pods are healthy before the API rolls:

Terminal window
kubectl get pods -n openagentic | grep -E 'milvus|etcd|minio'

If you do not want Milvus, the shipped Compose default already runs pgvector-only (SKIP_TOOL_SEMANTIC_CACHE=true) — just run docker compose up -d with no profile. To be explicit, set:

Terminal window
MILVUS_ENABLED=false
SKIP_TOOL_SEMANTIC_CACHE=true

With these set, the entrypoint skips the Milvus wait and uses pgvector inside Postgres for vector search.

Note: Milvus is optional. The Compose stack defaults to pgvector-only; the Helm chart deploys Milvus by default (milvus.enabled: true). The API only blocks on Milvus when it is enabled.

Prisma TLS error on boot (P1011)

Symptom. The API fails its schema step with a Prisma P1011 error: server does not support TLS.

Cause. Prisma db push opens a TLS connection when the DATABASE_URL carries sslmode=require, but the bundled pgvector Postgres does not terminate TLS, so the connection is rejected.

Fix. Do not require TLS against an inline pgvector Postgres. Set sslmode=disable on the DATABASE_URL you provide, either directly or in your values override:

Terminal window
DATABASE_URL=postgresql://openagentic:PASSWORD@postgres:5432/openagentic?sslmode=disable

Chat returns HTTP 400 “does not support tools”

Symptom. A chat request fails with HTTP 400 and the message does not support tools.

Cause. Agentic chat always attaches tools to the request, so the chat model must be tool-capable. A non-tool model (for example, Ollama gemma3:1b) is rejected. Ollama reports does not support tools for the gemma3 family.

Fix. Use a tool-capable chat model. On Ollama, the tool-capable families are qwen (including qwen2.5 and qwen3), gpt-oss, llama3.x, and mistral. The quick install path falls back to qwen2.5:7b. Alternatively, use a cloud model; gemini-2.5-flash is verified. Embedding models such as text-embedding-005 and nomic-embed-text do not need tool support.

Pods never become ready: provider:reload storm

Symptom. Two API pods loop indefinitely. The logs repeat Model capability discovery complete and Received provider:reload from peer, but the API never logs service started.

Cause. Two API replicas bounce the provider:reload pub/sub channel off each other, producing an infinite mutual model-rediscovery loop. Neither pod becomes ready.

Fix. Do not run more than one API replica. The chart pins the API Deployment to replicas: 1 for this reason. Keep it set to 1.

An upgrade briefly takes the API down and then brings up a single fresh pod. This is expected behavior, not a regression.

Embeddings ignore your Ollama URL

Symptom. The embedding pre-check connects to the wrong Ollama host and ignores OLLAMA_BASE_URL.

Cause. When the embedding provider is Ollama, the entrypoint’s embedding pre-check reads EMBEDDING_OLLAMA_BASE_URL first. It falls back to OLLAMA_BASE_URL, and then to http://ollama:11434, only if EMBEDDING_OLLAMA_BASE_URL is unset.

Fix. Set EMBEDDING_OLLAMA_BASE_URL to your Ollama endpoint when you pin the embedding host explicitly:

Terminal window
EMBEDDING_OLLAMA_BASE_URL=http://host.docker.internal:11434

Login or chat blocked when port-forwarding

Symptom. You reach the UI through a port-forward, but login or chat requests are blocked by CORS.

Cause. The API’s ALLOWED_ORIGINS does not include the localhost port that you use to reach the UI.

Fix. Add that origin to the comma-separated list. For a port-forward on :8080, set:

Terminal window
ALLOWED_ORIGINS=http://localhost:8080

First boot appears to hang

Symptom. The API takes several minutes to report healthy on a fresh install and appears stuck.

Cause. First boot performs real work in series: the entrypoint runs dependency health checks (Milvus, Redis, MCP Proxy, embedding model), the Prisma schema push (db push, which also creates the workflow tables), Milvus collection initialization, MCP tool indexing into pgvector, and, on Ollama, model cold-loads.

Fix. Allow a few minutes and watch progress instead of assuming a hang. The installer itself waits up to approximately three minutes for the API container to report healthy. Check the logs:

Terminal window
# Docker Compose
docker compose logs -f api


# Kubernetes
kubectl logs -n openagentic deployment/openagentic-api -f

Subsequent boots are significantly faster because dependencies are warm and the schema is already in place.

Cannot reach the UI on Kubernetes

Symptom. The stack is healthy, but you have no URL to open.

Cause. The UI Service is not exposed by default, because ingress.enabled is false.

Fix. Port-forward the ui Service, then open http://localhost:8080:

Terminal window
kubectl port-forward -n openagentic svc/ui 8080:80

Pair this with the ALLOWED_ORIGINS fix above so that login and chat are not blocked.

What’s next

  • Run the diagnostic first when something breaks:

    Terminal window
    curl -sSL https://install.openagentics.io | bash -s -- --doctor

  • If you are still stuck, check pod and container health with docker compose ps or kubectl get pods -n openagentic -o wide, then inspect the API logs:

    Terminal window
    # Docker Compose
    docker logs openagentic-api-1 --tail=100
    

    # Kubernetes
    kubectl -n openagentic logs deploy/api --tail=100

  • Review the Docker Compose and Kubernetes deployment guides.