# 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:

1. **Confirm how Valdr was started.** `valdr` and `valdr ui` start the web app on `127.0.0.1:<port>` (default `7777`). MCP hosts should launch `valdr pm`.
2. **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.
3. **Check your license in the UI.** Open **Settings > Settings** and confirm the current status and tier.
4. **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

{{< cards >}}
  {{< card link="./install/" title="Install" subtitle="Homebrew, PATH, and post-install verification" icon="download" >}}
  {{< card link="./license/" title="License" subtitle="Activation, tier checks, and license validation" icon="key" >}}
  {{< card link="./startup/" title="Startup" subtitle="Ports, credentials, data directories, and startup failures" icon="play" >}}
  {{< card link="./mcp/" title="MCP" subtitle="Connection, tool discovery, and host configuration issues" icon="code" >}}
  {{< card link="./providers/" title="Providers & Presets" subtitle="Credentials, models, and launcher configuration" icon="switch-horizontal" >}}
  {{< card link="./sessions/" title="Sessions & Worktrees" subtitle="Agent launches, worktree isolation, and cleanup" icon="terminal" >}}
  {{< card link="./packs/" title="Valdr Packs" subtitle="Import, validation, and archive problems" icon="cube" >}}
{{< /cards >}}

## 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](/valdr/docs/ui/system-monitoring/)
- 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
- **Local-first:** share only what you're comfortable sharing from your machine