Troubleshooting
Start with the health checklist for a fast overall check, then use the category sections below for a specific error message.
Quick health checklist
Section titled “Quick health checklist”Socket connection
Permissions
Credentials
Indexes tab
If any of these fail, fix that first — most downstream errors trace back to one of them.
Agent and LLM issues
Section titled “Agent and LLM issues”Agent stops or gives a truncated answer
The model hit its Max Completion Tokens limit. Increase the value in the agent’s model settings; check nested agents too if the issue appears mid-chain.
Content-policy or safety rejection (400 error)
The message or instructions triggered the provider’s safety mechanism. Avoid sensitive topics and phrasing that reads like a prompt-injection attempt (for example, “ignore user input”); state the purpose of any such instruction clearly.
Rate limit exceeded (429 error)
Shared models on your deployment share per-second/minute/day limits across every user. Wait and retry, or switch models.
Context length exceeded
Input plus history exceeded the model’s context window. Reduce the input, turn on context management, or index the source instead of pasting it directly.
Multiple output variables all get the same content
Turn on Structured Output when an LLM node has more than one output variable, and instruct the model to return JSON keyed by your variable names.
Pipeline configuration issues
Section titled “Pipeline configuration issues”Entry point is not defined
Every pipeline needs one designated starting node — open the node’s three-dot menu and select Entry Point.
Task is required / empty task field
A node (Agent, Decision, Router, and others) has an empty Task field — required fields must be filled before the pipeline can run.
Node ignores the provided input
The task field must explicitly reference the variable, using an f-string or the variable picker — listing a variable under Input alone does not pass it to the node automatically.
Found edge starting at unknown node
A node has no agent or toolkit selected in its dropdown — select one.
Toolkit and integration issues
Section titled “Toolkit and integration issues”Permission error during indexing
The connected account’s token cannot see one or more items. Narrow the source with a filter (JQL for Jira, CQL for Confluence) and retry — items deleted mid-run also surface this way.
Authentication fails (401/403)
Recheck the credential’s key or token for typos, extra whitespace, or expiry, and confirm the authentication method (basic vs. bearer) matches what the target service expects.
A toolkit returns far fewer results than expected
Its configuration has a Limit field capping results per request — raise it in the toolkit’s configuration.
Toolkit fails to save with a missing-field validation error
A required field is empty after an import or an update to the toolkit’s schema — review every configuration section, including advanced settings, and fill anything marked required.
MCP issues
Section titled “MCP issues”MCP shows Disconnected
For a Remote MCP, verify the server URL is reachable and its authentication has not expired. Elitea’s MCP connections are HTTP-only — there is no local, STDIO-based server or client to run first.
No tools appear after connecting an MCP
Reload the MCP’s configuration page, and confirm the server actually exposes tools once connected.
Desktop app issues
Section titled “Desktop app issues”The desktop app shows "[Error] System env missing" after sign-in
The desktop app 7.3.0 shows this page after sign-in, listing VITE_SERVER_URL, VITE_BASE_URI and VITE_PUBLIC_PROJECT_ID. Nothing is wrong with your deployment or your settings: the app read its configuration before sign-in had supplied it, and kept the empty result. Install a newer desktop release. Signing out or reinstalling 7.3.0 does not help.
Operator checks
Section titled “Operator checks”Two different things answer “is the platform healthy,” at two different levels.
Infrastructure liveness and readiness
Section titled “Infrastructure liveness and readiness”elitea-main exposes unauthenticated health endpoints for your load balancer, orchestrator, or uptime check:
GET /healthz— liveness. Answers once the process is up; it does not check dependencies.GET /readyz— readiness. Checks the dependencies the service actually needs (for example, the database) and reports which one failed if it is not ready.
Point your platform’s health probe (Kubernetes liveness/readiness probe, or an external uptime monitor) at these rather than at an authenticated API route.
The Health tab (application-level)
Section titled “The Health tab (application-level)”Inside the app, Settings › Analytics › Health (gated by the analytics_enabled admin flag — see Features and configuration) reports on the LLM gateway path specifically:
- Error codes — a table of upstream and gateway error codes seen recently, by count. This reads the gateway’s per-request log, not the billing ledger, so a call that was refused by a budget, rejected by policy, or failed upstream shows up here even though it never generated a billed event.
- Model health — which configured models are currently returning errors, and how often.
- Activity trend — a day-by-day chart of request volume.
Use the infrastructure endpoints to answer “is the service up,” and the Health tab to answer “are calls through the LLM gateway succeeding.” For upgrades, backups, scaling, and a fuller troubleshooting table for a Kubernetes deployment, see Day-2 operations.