Common problems with the local stack, collected from the topic documentation. Each entry links to the page with the full explanation.
| Symptom | Likely cause | What to do |
|---|---|---|
The stack does not start; ai-control-service or embabel-agent-runtime fails at boot. |
OPENAI_API_KEY missing in .env. |
cp .env.example .env and set OPENAI_API_KEY. It is mandatory to boot. Quickstart |
Health is UP, but every agent run fails on the first LLM call. |
Ollama not running, model not pulled, or not reachable from the containers. Health does not probe Ollama. | Check ollama list for qwen3.6:27b, keep the daemon running. On Linux, see the networking warning. LLM providers |
Agent runs fail after setting OLLAMA_BASE_URL=http://localhost:11434 in .env. |
.env applies to the container, whose loopback has no Ollama. |
Remove the override, or point it at an address reachable from the container. LLM providers |
LLM calls fail with 401 from the gateway (two requests per call). |
Wrong or missing LITELLM_VIRTUAL_KEY, or local-seed did not run. |
Check docker compose logs local-seed; this is expected fail-closed behaviour. Known limitations |
| The LiteLLM gateway is down and you need agents to work. | Gateway outage. | Revert B: LLM_CODING_ROUTE=direct in .env, then docker compose up -d embabel-agent-runtime. LLM providers |
| Runs take very long or time out. | Several agents on a large local model; worst case 600 s per LLM call. | Expected locally; jobs wait up to WORKFLOW_AGENT_TIMEOUT (3600 s). LLM providers |
Login redirects to :3000, or “invalid redirect URI”. |
Keycloak database still holds the old realm from before the landing app was removed. | Re-import the realm or edit the openjcockpit client. Authentication |
A workflow start returns BLOCKED. |
No agents linked, all agents denied by policy, or an invalid git-workspace ticket. | Read the reason; check docker compose logs opa. Agents and workflows |
| Agent tool calls are denied by policy. | Missing workflowId/customerId in the policy input, e.g. an agent run outside a workflow. |
Start agents through a workflow. Policy enforcement |
A manual workflow start returns 409 SPEC_QUEUE_ITEM_ACTIVE. |
A spec queue item is active for this project. | Wait, or pause/cancel the queue item. Spec queue |
| The spec queue halted. | A failed item (for example START_OUTCOME_UNKNOWN or MERGE_WAIT_TIMEOUT). |
Retry, skip or remove the item, then resume the queue. Check the workflow executions for a still-running run. Spec queue |
| A workflow run fails with “Local agent … failed: The agent runtime is unavailable” or “not configured”. | embabel-agent-runtime is down, unreachable at EMBABEL_AGENT_RUNTIME_BASE_URL, or its Keycloak client is missing. |
docker compose ps embabel-agent-runtime, curl localhost:8092/actuator/health/readiness; check AGENT_SERVICE_CLIENT_SECRET and that local-seed completed. Agent runtime |
Agents answer TENANT_FORBIDDEN/UNAVAILABLE and tool calls are denied (“policy decision unavailable”). |
The runtime cannot reach embabel-agent-service (EMBABEL_AGENT_SERVICE_BASE_URL) or authenticate as openjcockpit-agent-runtime; it fails closed. |
docker compose logs embabel-agent-runtime \| grep agent-service.call.failed; check AGENT_RUNTIME_CLIENT_SECRET. |
| A2A calls through LiteLLM fail with a connection error after the split. | LiteLLM still routes to embabel-agent-service:8081. |
The agent urls in infrastructure/litellm/config.yaml must be http://embabel-agent-runtime:8082/a2a/<agent>; restart LiteLLM. |
| The dashboard shows “run state lost”. | Unknown or expired run id, e.g. after a restart of embabel-agent-service (paused runs are in memory). |
Start the workflow again. Approval gates |
| A git-workspace job fails to start its container. | The job image is not pulled automatically. | docker pull eclipse-temurin:25-jre Git integration |
A dashboard start on a project returns 502. |
Cloning the project repository failed (URL or credential). | Check the project URL and Settings → Git credentials. Git integration |
| A workflow is missing from the list, or a policy/approval audit record is missing. | A malformed YAML file was skipped. | docker compose logs embabel-agent-service \| grep definition.file.read.failed. Runbooks |
GET /api/workflows returns 502. |
The upstream listing in embabel-agent-service failed (different from an empty 200). |
See the service log. Runbooks |
embabel-agent-service fails at boot after a rollback. |
Older code cannot parse approvalGate: in saved workflows, or a seeded workflow file is malformed. |
Approval gates rollback hazard, Runbooks |
| Old workflows load without agents. | Pre-catalogue workflow YAML with old stage ids. | Re-link agents in Workflow Design. Agents and workflows |
Marketplace requests go to /skills/skills. |
The stored marketplace URL already ends in /skills. |
Register the base URL. Skills Hub |
Port 4000 already in use when running E2E or Vite. |
The Vite dev server and the containerised dashboard both bind 4000 in E2E modes. |
Use one E2E mode at a time. Testing |
A local, non-Docker embabel-agent-service does not show your workflows. |
It uses ${java.io.tmpdir}/embabel-workflow-definitions, not the Compose volume. |
Set WORKFLOW_DEFINITIONS_PATH. Runbooks |
Still stuck? Check the logs (see Runbooks) and open an issue on GitHub. Report security problems privately via the security policy.