FAQ and troubleshooting
Verified with Cortex on October 2, 2026
This page gathers frequently asked questions about Cortex and fixes for common installation and configuration problems.
Frequently asked questions
Does Cortex send data to Wavertex?
We found no telemetry, analytics, update check or "phone-home" call in the code of the gateway, the web interface and the AI engine (version checked on 5 October 2026). At run time, the only outgoing connections go to services you configure: the LLM destinations (they receive the message already redacted), your OIDC or SAML identity provider, the web search engine and the AI engine if enabled, and the inference and embedding servers of the AI engine. The pricing:sync administration command fetches prices online only if you pass it --online; without that argument, it reads a price snapshot shipped with the repository. The /metrics endpoint answers only if you set METRICS_TOKEN, and it is up to your monitoring tool to query it. The web interface is built and started with the anonymous Next.js telemetry turned off (NEXT_TELEMETRY_DISABLED=1). One caveat: in the Cortex containers, every pnpm command (the web interface start, or an administration command such as pricing:sync run inside a container) queries the public npm registry to check the pnpm version pinned by the project; without access to that registry, the command still completes, but one to two minutes later in our tests.
Does Cortex work without the AI engine?
Yes. The AI engine is optional: without it, pattern and secret DLP filtering still applies, and no essential feature depends on it. It adds name recognition (DLP 1.5), detection by a local model (DLP 2), and the extraction and embeddings of the knowledge base. See Installation to enable it.
Which models are supported?
Cortex connects to the catalog's providers (openai, anthropic, azure_openai, google_gemini, mistral, groq, together_ai, openrouter, deepseek, xai) and to local engines (ollama, lm_studio, vllm), as well as any compatible service through custom_openai, custom_anthropic or custom_local. You choose the authorized models for each destination. See Providers and models.
Does a "light" DLP profile reduce filtering?
Not today. A destination's profile is a label: the gateway records it in the audit journal and displays it, but the code draws no difference in processing from it. DLP scanning applies the same way to every destination. The console reserves "Light profile" for the private network and requires an approval for an address that is not private (see DLP rules).
Troubleshooting
A .env setting seems ignored. Why?
A container receives a variable only if docker-compose.yml lists it in its environment: block. Variables marked "Host-side only" in .env.example are not there: changing them does nothing in the containers. Add the variable to the service's environment: block, or start the process on the host with the value. The pnpm --filter gateway … commands do not read .env either; only the root pnpm migration:run shortcut does. See Configuration.
The AI engine is reported as unavailable. What happens?
The gateway probes the engine every 30 seconds. If it cannot reach it, it reports the engine as unavailable in its capabilities, with no error for employees, and requests continue on DLP 1 alone. When a detection call fails or times out, a "Request sent with DLP 1 only (AI engine degraded)" entry is added to the audit journal. Check that AI_ENGINE_URL is an origin (scheme, host, port, no path) that the gateway container can reach, and that the engine is running.
Documents stay in the queue. What should I check?
The "Knowledge-base posture" card gives the reason: the AI engine is not answering, or no embedding model is declared. In both cases uploads wait in the queue and are processed once the situation is fixed; if the engine is disabled in the configuration, they are refused. Also check that RAG_INGEST_INTERVAL_MS is not 0: that value disables processing and documents stay "Uploaded". See Knowledge base.
I cannot stay signed in when I open Cortex over http through a local network address. Why?
Cortex's images start in production mode, and the gateway then marks the session cookie "Secure". Most browsers refuse to keep such a cookie on an unencrypted http connection, except on localhost. Serve Cortex over HTTPS (behind a reverse proxy) rather than over http on a network IP address.
Every API route answers 500 after docker compose up.
docker compose up starts the containers without ever running migrations: the schema does not exist yet. This is deliberate. Run the migration and provisioning sequence of the first installation before signing in.
"tenant key mismatch" error, or a 500 on the first message after provisioning.
The KMS_LOCAL_KEK value used for the provisioning command differs from the running gateway's, which then cannot decrypt the tenant's key. Run provisioning again with the same value as the gateway service.
migration:run fails with "password authentication failed for user "cortex_owner"".
The pnpm --filter gateway … commands read their configuration from their own environment only, not .env (the root pnpm migration:run shortcut does read it). Put in MIGRATION_DATABASE_URL the password the role really has: the CORTEX_OWNER_PASSWORD value at the time the volume was first initialized. Changing .env later does not change an existing role's password.
A port is already in use.
One of the published ports is taken on the host: 3000 (web), 4000 (gateway), 5432 (PostgreSQL) or 8080 (Keycloak, sso profile). Free it, or change it with WEB_PORT, GATEWAY_PORT, POSTGRES_PORT or KEYCLOAK_PORT in .env before running docker compose up -d again.