Troubleshooting¶
Common problems and how to fix them.
Agent not responding¶
# Is it running?
docker compose ps
# What's in the logs?
docker compose logs --tail=50 my-agent
# Restart it
docker compose restart my-agent
“Model not found”¶
The LLM model isn’t pulled yet:
docker exec <ollama-container> ollama pull qwen2.5:3b
Or check which models are available:
docker exec <ollama-container> ollama list
Slow responses¶
Cause: Model too large for your hardware.
Fix: Use a smaller model:
# config.py
LLM_CONFIG = {"provider": "ollama", "model": "qwen2.5:1.5b"} # Smaller, faster
Or check RAM usage: docker stats
Semantic Layer not finding agents¶
# Are agent cards in the right place?
ls services/semantic_layer/agent_cards/
# Is Weaviate healthy?
curl http://localhost:8081/v1/.well-known/ready
# Restart to re-index
docker compose restart <project>-semantic-layer
“Port already in use”¶
Another process is using that port. Either stop it or change the port in compose.yaml:
ports:
- "8003:8002" # Map to a different host port
A2A connection refused¶
The target agent isn’t ready yet. Check:
# Is the target running?
docker compose ps
# Can you reach it?
curl http://<target-container>:<port>/health
Common cause: the agent depends on Semantic Layer which depends on Weaviate. Wait for health checks to pass.
“Session terminated” from MCP¶
The Semantic Layer connection dropped. MCPToolkit.call_with_retry() handles this automatically:
result = await toolkit.call_with_retry("my_tool", max_retries=3, param="value")
Container keeps restarting¶
Check logs for the crash reason:
docker compose logs --tail=100 <container>
Common causes:
Missing environment variable
Agent card file not found
Python import error (missing dependency)