Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance for diagnosing and resolving issues within the OpenPoke orchestration stack. It covers common failure points in multi-agent communication, tool execution, external service integrations (Gmail/Composio), and data persistence.
Troubleshooting in OpenPoke involves examining the interactions between the Next.js frontend, the FastAPI backend, and the LLM providers via OpenRouter. The system utilizes structured logging and specific error-handling patterns within both the InteractionAgentRuntime and ExecutionAgentRuntime to surface issues.
Sources: README.md, server/agents/interaction_agent/runtime.py:44-53
Agent Orchestration and LLM Errors
Agent failures typically occur during the LLM interaction loop or tool invocation. Both primary runtimes enforce a MAX_TOOL_ITERATIONS limit (set to 8) to prevent infinite loops when agents fail to reach a final response.
Interaction Loop Failures
The InteractionAgentRuntime manages the high-level conversation. If the LLM provides an invalid response or exceeds the iteration limit, the system returns an InteractionResult with success=False.
Execution Agent Failures
The ExecutionAgentRuntime focuses on task fulfillment. Errors here are often captured and recorded in the agent's history via record_response. Common errors include LLM response did not include an assistant message or Reached tool iteration limit.
Sources: server/agents/execution_agent/runtime.py:59-130
| Error Type | Source | Possible Cause |
|---|---|---|
OpenRouter API key not configured | Configuration | Missing OPENROUTER_API_KEY in .env. |
Reached tool iteration limit | Runtime | Agent stuck in a loop or cannot satisfy goal with tools. |
Tool execution crashed | Tools | Internal logic error in a registered tool function. |
invalid json | LLM Response | The LLM returned malformed tool arguments. |
Sources: server/agents/interaction_agent/runtime.py:196, server/agents/execution_agent/runtime.py:44, server/agents/execution_agent/runtime.py:121
Gmail and Integration Connectivity
Gmail workflows depend on Composio. Issues often manifest as "Gmail not connected" or authentication failures.
Connection Diagnostics
The frontend provides status indicators in the SettingsModal. If the Gmail status shows "Not connected," users should verify the userId and connectionRequestId stored in localStorage.
Email Search Task Errors
The task_email_search tool includes specific validation steps that can be used to identify issues:
ERROR_GMAIL_NOT_CONNECTED: Thecomposio_user_idcould not be retrieved.ERROR_OPENROUTER_NOT_CONFIGURED: Missing API keys required for the sub-orchestration loop.ERROR_ITERATION_LIMIT: The sub-agent could not finalize the email selection within 8 calls.
Sources: server/agents/execution_agent/tasks/search_email/tool.py:31-40, server/agents/execution_agent/tasks/search_email/tool.py:73-89
Data Persistence and Working Memory
OpenPoke uses file-based logging for conversation history and "working memory" summarization.
Log Corruption or Access Issues
The WorkingMemoryLog class handles file I/O for the memory briefing. Failures in this component are logged but may lead to the assistant "forgetting" recent context.
- Initialization: If
server/data/conversation/poke_working_memory.logcannot be created, check filesystem permissions. - Atomic Writes: The system uses a
.tmpfile swap pattern to prevent log corruption during write failures.
# server/services/conversation/summarization/working_memory_log.py:133-140
temp_path = self._path.with_suffix(".tmp")
data = "".join(lines)
with self._lock:
try:
temp_path.write_text(data, encoding="utf-8")
temp_path.replace(self._path)
Sources: server/services/conversation/summarization/working_memory_log.py:53-65, server/services/conversation/summarization/working_memory_log.py:133-145
Summarization Failures
When summarization_enabled is true, the InteractionAgentRuntime prefers the working memory transcript. If the summary is empty or malformed, the agent may lose access to chronological context.
Sources: server/agents/interaction_agent/runtime.py:161-166, server/services/conversation/summarization/working_memory_log.py:151-169
Frontend and API Proxy Issues
The Next.js web UI proxies requests to the Python server. If the UI remains in a "Typing" state indefinitely, check the browser console for poll failures.
Polling Failures
The frontend polls /api/chat/history every 1.5 seconds (POLL_INTERVAL_MS). If the backend process crashes, these requests will fail with a 502 Upstream Error.
| Symptom | Component | Resolution |
|---|---|---|
| "Failed to fetch" in Console | Proxy | Ensure PY_SERVER_URL is set to the correct FastAPI port (default 8001). |
| Infinite Typing Indicator | UI Polling | Check if isWaitingForResponse is being reset; check maxPollAttempts (default 30). |
| Empty Chat History | Conversation Log | Ensure server/data/ directory is writable. |
Sources: web/app/page.tsx:21, web/app/page.tsx:162-192, web/app/api/chat/route.ts:31-33
Timezone Detection
The system automatically detects the browser's timezone. If relative times (e.g., "tomorrow") are resolving incorrectly, verify that the timezone is correctly sent to /api/timezone and stored in the local settings state.
Sources: web/app/page.tsx:69-90, web/components/SettingsModal.tsx:14-25
OpenPoke relies on granular logging across agent runtimes and proxy routes. When troubleshooting, verify environment variables in the shared .env file first, followed by inspecting the FastAPI server logs for tool execution traces.