Troubleshooting & Debugging
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork provides a robust framework for identifying, reporting, and resolving issues across its distributed architecture. The system encompasses local desktop environments, remote worker nodes, and the core OpenCode engine. Debugging is facilitated through specialized UI panels, runtime reports, automated evaluation flows, and architecture validation gates.
The primary objective of the troubleshooting infrastructure is to provide "auditable" evidence of what happened, when, and why during agentic executions. This is achieved by surfacing internal state through diagnostics bundles and developer logs, which are critical for maintaining the Local-first, cloud-ready philosophy of the project.
Sources: README.md:12-25, SUPPORT.md:1-10
Diagnostic Tools and Reports
OpenWork surfaces internal runtime information through the Settings menu, specifically designed for bug reporting and system health monitoring.
Runtime Debug Report
The Runtime Debug Report is a comprehensive diagnostics snapshot available in Settings -> Debug. It provides a readable JSON export of the current system state, including environment variables, binary paths, and active workspace configurations.
| Component | Description |
|---|---|
| Commit SHA | The specific build version currently running. |
| Binary Paths | Paths to the OpenCode and OpenWork server binaries. |
| Token Sources | Identification of where authorization tokens (CLI, generated, etc.) originated. |
| Runtime Mode | Identification of Host mode vs. Client mode. |
Sources: README.md:65-70, apps/app/src/app/utils/index.ts:250-280, evals/react-session-flows.md:380-400
Developer Log Stream
The Developer Log Stream captures real-time events from the application, workspace, and session levels. It is particularly useful for debugging performance issues or intermittent synchronization failures. Users are encouraged to export these logs (in .log format) when filing issues.
Sources: SUPPORT.md:10-15, evals/react-session-flows.md:410-420
Automated Evals and Testing
The project utilizes "human-readable scenarios" called Evals to verify end-to-end behavior. Unlike unit tests, these exercise the full stack: OpenCode, OpenWork server, and the React UI.
Testing Architecture
Testing can be performed in three primary environments:
- Daytona Cloud Sandbox: A real Electron app running in a cloud environment (recommended).
- Local Electron: Running the dev app locally via
pnpm devand using CDP tools againsthttp://127.0.0.1:9825. - Manual Browser: Following step-by-step checklists in a standard browser.
The diagram shows how automated evaluation tools interact with different environments to verify the integrated stack.
Sources: evals/README.md:1-40, evals/react-session-flows.md:1-30
Chrome DevTools Protocol (CDP)
Debugging and automation heavily rely on the browser_* toolset, which communicates with the Electron renderer via CDP. These tools allow for deep inspection of the accessibility tree and console messages.
Sources: evals/README.md:45-55, evals/react-session-flows.md:35-50
Common Issues and Resolutions
Architecture Mismatch
The ArchitectureMismatchGate is a security and stability feature that blocks startup if the application architecture (e.g., x64) does not match the system architecture (e.g., arm64). This prevents unpredictable issues with runtime sidecars and browser tooling.
The flow represents the logic used to prevent the execution of incompatible binaries on host systems.
Sources: apps/app/src/react-app/shell/architecture-mismatch-gate.tsx:50-120
Connection and Sandbox Failures
Troubleshooting remote or sandbox workspaces requires checking specific network and daemon statuses.
| Error Category | Indicators | Suggested Action |
|---|---|---|
| Docker Offline | "cannot connect to docker daemon", "docker.sock" | Start Docker Desktop and test connection. |
| Network Error | "connection refused", "timeout", "enotfound" | Check LAN/mDNS URLs and host token validity. |
| Corrupt Cache | "enoent", ".cache/opencode" | Use "Repair cache" in Settings to rebuild local data. |
Sources: apps/app/src/app/utils/index.ts:315-360, apps/app/src/app/utils/index.ts:400-415
UI Performance: Infinite Render Loops
A critical debugging step for developers is monitoring the JS console for Maximum update depth exceeded warnings. This typically indicates a re-render loop in the settings route, often caused by unstable dependencies in useEffect hooks.
Sources: evals/react-session-flows.md:50-60, evals/react-session-flows.md:330-340
Toy UI for Host Debugging
The Toy UI is a "host contract harness" served directly by openwork-server. It is used to test server-side logic (SSE events, token minting, workspace imports) independently of the main React application.
Key Toy UI Features:
- SSE Connection: Visualizes the stream of
data:events for real-time update debugging. - Token Management: Allows minting and revoking tokens directly against the host API.
- Harness Mode: Serves as a simplified client to verify API responses for skills, plugins, and MCP servers.
Sources: apps/server/src/toy-ui.ts:160-220, apps/server/src/toy-ui.ts:450-500
Security and Privacy Debugging
Debugging involves sensitive data; therefore, OpenWork includes an automatic redaction mechanism.
// Example of the redaction logic applied to logs and exports
if (
lowerKey.includes("api_key") ||
lowerKey.includes("token") ||
lowerKey.includes("secret")
) {
return "[redacted]";
}
Sources: apps/app/src/app/utils/index.ts:255-275, apps/app/src/app/utils/index.ts:420-425
Summary: Troubleshooting in OpenWork is a multi-layered process that ranges from simple log exports for non-technical users to complex CDP-based automation for developers. By centralizing diagnostics and architecture gates, the system ensures that issues are identified early and reported with sufficient technical context.