Troubleshooting
Troubleshooting
{"content":"When something doesn't work, start here. This section covers the most common issues across install, licensing, startup, MCP, providers, sessions, and packs, with fixes aligned to the current Valdr app and UI.\n\n## Quick triage\n\nStart with these checks whenever something feels off:\n\n1. **Confirm how Valdr was started.** `valdr` and `valdr ui` start the web app on `127.0.0.1:\u003cport\u003e` (default `7777`). MCP hosts should launch `valdr pm`.\n2. **Check [System Monitoring](/valdr/docs/ui/system-monitoring/).** Use it to confirm the process is alive, find the exact `PM DB Path`, and inspect CPU, memory, and event-loop health.\n3. **Check your license in the UI.** Open **Settings \u003e Settings** and confirm the current status and tier.\n4. **If the issue is MCP-specific, inspect your MCP host config.** Confirm it launches `valdr pm`, uses the expected `--pm-home`, and has the right working directory and environment variables.\n\n## By category\n\n{{\u003c cards \u003e}}\n {{\u003c card link=\"./install/\" title=\"Install\" subtitle=\"Homebrew, PATH, and post-install verification\" icon=\"download\" \u003e}}\n {{\u003c card link=\"./license/\" title=\"License\" subtitle=\"Activation, tier checks, and license validation\" icon=\"key\" \u003e}}\n {{\u003c card link=\"./startup/\" title=\"Startup\" subtitle=\"Ports, credentials, data directories, and startup failures\" icon=\"play\" \u003e}}\n {{\u003c card link=\"./mcp/\" title=\"MCP\" subtitle=\"Connection, tool discovery, and host configuration issues\" icon=\"code\" \u003e}}\n {{\u003c card link=\"./providers/\" title=\"Providers \u0026 Presets\" subtitle=\"Credentials, models, and launcher configuration\" icon=\"switch-horizontal\" \u003e}}\n {{\u003c card link=\"./sessions/\" title=\"Sessions \u0026 Worktrees\" subtitle=\"Agent launches, worktree isolation, and cleanup\" icon=\"terminal\" \u003e}}\n {{\u003c card link=\"./packs/\" title=\"Valdr Packs\" subtitle=\"Import, validation, and archive problems\" icon=\"cube\" \u003e}}\n{{\u003c /cards \u003e}}\n\n## Still stuck?\n\nIf you've worked through the relevant section and still need help:\n\n- Copy the **Version**, **Runtime**, **Platform**, and **PM DB Path** fields from [System Monitoring](/valdr/docs/ui/system-monitoring/)\n- Open an issue at [projectviking-ai/valdr](https://github.com/projectviking-ai/valdr/issues) with what you expected, what happened, and how you started Valdr\n- **Local-first:** share only what you're comfortable sharing from your machine","description":"Diagnose and fix the most common issues with Valdr — install, licensing, startup, MCP, providers, sessions, and packs.","title":"Troubleshooting"}
When something doesn’t work, start here. This section covers the most common issues across install, licensing, startup, MCP, providers, sessions, and packs, with fixes aligned to the current Valdr app and UI.
Quick triage
Start with these checks whenever something feels off:
- Confirm how Valdr was started.
valdrandvaldr uistart the web app on127.0.0.1:<port>(default7777). MCP hosts should launchvaldr pm. - Check System Monitoring. Use it to confirm the process is alive, find the exact
PM DB Path, and inspect CPU, memory, and event-loop health. - Check your license in the UI. Open Settings > Settings and confirm the current status and tier.
- If the issue is MCP-specific, inspect your MCP host config. Confirm it launches
valdr pm, uses the expected--pm-home, and has the right working directory and environment variables.
By category
Homebrew, PATH, and post-install verification
Activation, tier checks, and license validation
Ports, credentials, data directories, and startup failures
Connection, tool discovery, and host configuration issues
Credentials, models, and launcher configuration
Agent launches, worktree isolation, and cleanup
Import, validation, and archive problems
Still stuck?
If you’ve worked through the relevant section and still need help:
- Copy the Version, Runtime, Platform, and PM DB Path fields from System Monitoring
- Open an issue at projectviking-ai/valdr with what you expected, what happened, and how you started Valdr
- Local-first: share only what you’re comfortable sharing from your machine