Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
The Open Claude Cowork application relies on a multi-tiered architecture involving an Electron frontend, a Node.js/Express backend, and multiple external AI and tool providers (Anthropic, Opencode, and Composio). Troubleshooting involves verifying local environment configurations, network connectivity between the Electron client and the backend server, and the validity of API credentials.
This guide focuses on resolving common issues related to connectivity, API authentication, session persistence, and streaming failures.
Connection and Initialization Issues
A frequent point of failure is the inability of the Electron frontend to communicate with the Express backend, or the backend's failure to initialize required tool routing sessions.
Backend Connectivity
The backend server must be running on port 3001 for the Electron app to function. If the "Failed to connect to backend" error appears, users should verify that the server is active in a separate terminal.
Sources: README.md:275-278, server/server.js:18
Composio Session Initialization
On startup, the backend attempts to pre-initialize a Composio session to generate a Managed Control Plane (MCP) URL. If this fails, the app may not be able to route tool calls.
The diagram above shows the backend initialization flow for tool routing.
Sources: server/server.js:30-45
Common Initialization Errors
| Symptom | Probable Cause | Resolution |
|---|---|---|
| "Failed to connect to backend" | Backend server not running on port 3001 | Run cd server && npm start in a separate terminal |
| "Provider not available" | API Key missing in .env | Verify ANTHROPIC_API_KEY or OPENCODE_API_KEY exists |
| "Opencode models not responding" | Opencode server not running | Ensure Opencode service is active on configured port |
Sources: README.md:275-300, server/server.js:181-190
API and Authentication Troubleshooting
The application requires specific API keys for different providers. Improperly formatted or missing keys in the .env file are primary causes of request failures.
Environment Variable Configuration
The setup.sh script automates the creation of the .env file, but manual verification is often required.
- Anthropic Key: Must start with
sk-ant-. - Composio Key: Retrieved via
composio whoamiduring setup. - Opencode Key: Required if using the Opencode provider.
Sources: setup.sh:65-95, README.md:120-135, README.md:280-285
Provider Validation Logic
The backend validates the provider selection for every request. If a provider is requested but its SDK was not successfully initialized (usually due to missing keys), the server returns a 400 error.
Sources: server/server.js:93-100
Streaming and Response Failures
The application uses Server-Sent Events (SSE) for real-time response delivery. Network interruptions or SDK timeouts can lead to "slow" or "incomplete" streaming.
Heartbeat and Timeout Management
The backend implements a 15-second heartbeat to keep SSE connections alive. On the frontend, a 5-minute watchdog monitors for data reception.
The sequence diagram illustrates the heartbeat mechanism used to prevent connection silent drops.
Sources: server/server.js:107-115, renderer/renderer.js:564-570
Handling Aborted Requests
If a user clicks the "Stop" button or switches chats during an active stream, the application must abort the request both on the client and the server to prevent resource leaks.
- Frontend: Calls
window.electronAPI.abortCurrentRequest(). - Backend: The
/api/abortendpoint triggers the provider'sabort(chatId)method.
Sources: renderer/renderer.js:514-539, server/server.js:154-177, server/providers/claude-provider.js:25-34
Session Persistence Issues
Session management differs by provider. The Claude provider uses the Claude Agent SDK's built-in session resumption.
Claude Session Resumption
If a chatId is provided, the ClaudeProvider attempts to retrieve a stored session_id. If found, it uses the resume option in the SDK call.
// From server/providers/claude-provider.js
const existingSessionId = chatId ? this.getSession(chatId) : null;
if (existingSessionId) {
queryOptions.resume = existingSessionId;
console.log('[Claude] Resuming session:', existingSessionId);
}
Sources: server/providers/claude-provider.js:65-70
Common Session Failures
- Missing
chatId: If the frontend fails to pass thechatId, a new session is created every time, losing context. - Backend Restart: Provider sessions are typically stored in-memory (via
this.sessionsin the provider class); restarting the backend wipes active sessions. - LocalStorage Errors: The frontend stores chat history and the last active
currentChatIdin browserlocalStorage. If this is cleared, the link to server-side sessions may be lost.
Sources: renderer/renderer.js:84-110, README.md:287-290, server/server.js:132-135
Tool Integration and MCP Failures
Tool calls are routed through Composio. Failures here usually stem from remote MCP URL unreachable states or authentication errors.
Tool Call Statuses
Users can monitor the status of tool calls in the "Progress" sidebar. The application tracks three specific states:
- Running: The tool has been invoked, and the backend is waiting for the result.
- Success: The tool returned a result.
- Error: The tool execution failed.
Sources: renderer/renderer.js:933-945, renderer/index.html:200-220
Remote MCP Configuration
Opencode requires a valid server/opencode.json file. This file is automatically updated by the backend on startup with the remote Composio MCP URL. If tool calls fail specifically for Opencode, verify this file contains valid JSON with a remote type URL.
Sources: server/server.js:47-60, README.md:235-255
Conclusion
Most issues in Open Claude Cowork can be resolved by ensuring the dual-process architecture (Terminal 1 for Backend, Terminal 2 for Electron) is correctly maintained and that the .env file contains valid, properly formatted API keys for the selected AI and tool providers.
Sources: README.md:140-155, setup.sh:110-125