forked from HomeLab/unraid-mcp
183db70d97
Resolves review threads: - PRRT_kwDOO6Hdxs50mcYz: oidc/validate_session now documents required `token` - PRRT_kwDOO6Hdxs50mcY8: setting/update corrected to require `settings_input` - PRRT_kwDOO6Hdxs50mcZE: rclone/create_remote corrected to `provider_type`+`config_data` - PRRT_kwDOO6Hdxs50mcZL: disk/logs corrected to `log_path`+`tail_lines` - PRRT_kwDOO6Hdxs50mcZe: parity_progress added to event-driven subscriptions list - PRRT_kwDOO6Hdxs50mcZh: log_tail README example now includes required `path` - PRRT_kwDOO6Hdxs50mcaR: parity_start quick-reference now includes required `correct=False` - PRRT_kwDOO6Hdxs50mcaq: array_state documented as "may show" not "will always show" - PRRT_kwDOO6Hdxs50mnR8: key/create roles is optional; add_role/remove_role use `roles` (plural) - PRRT_kwDOO6Hdxs50mnRd: endpoints.md heading moved before blockquote (MD041) - PRRT_kwDOO6Hdxs50mnTB: test_resources.py uses _get_resource() helper instead of raw internals - PRRT_kwDOO6Hdxs50mYkZ: N/A — _build_google_auth removed in prior refactor commit - PRRT_kwDOO6Hdxs50mnQf: N/A — plugin.json already at 1.1.2, matches pyproject.toml - PRRT_kwDOO6Hdxs50mnQ7: N/A — blank line already present in CLAUDE.md - PRRT_kwDOO6Hdxs50mnRD: N/A — fastmcp.http.json removed in prior refactor commit - PRRT_kwDOO6Hdxs50mnRH: N/A — blank line already present in README.md - PRRT_kwDOO6Hdxs50mnSW: N/A — test_auth_builder.py removed in prior refactor commit
110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
# Unraid MCP — Troubleshooting Guide
|
|
|
|
## Credentials Not Configured
|
|
|
|
**Error:** `CredentialsNotConfiguredError` or message containing `~/.unraid-mcp/.env`
|
|
|
|
**Fix:** Run setup to configure credentials interactively:
|
|
|
|
```python
|
|
unraid(action="health", subaction="setup")
|
|
```
|
|
|
|
This writes `UNRAID_API_URL` and `UNRAID_API_KEY` to `~/.unraid-mcp/.env`. Re-run at any time to update or rotate credentials.
|
|
|
|
---
|
|
|
|
## Connection Failed / API Unreachable
|
|
|
|
**Symptoms:** Timeout, connection refused, network error
|
|
|
|
**Diagnostic steps:**
|
|
|
|
1. Test basic connectivity:
|
|
|
|
```python
|
|
unraid(action="health", subaction="test_connection")
|
|
```
|
|
|
|
1. Full diagnostic report:
|
|
|
|
```python
|
|
unraid(action="health", subaction="diagnose")
|
|
```
|
|
|
|
1. Check that `UNRAID_API_URL` in `~/.unraid-mcp/.env` points to the correct Unraid GraphQL endpoint.
|
|
|
|
1. Verify the API key has the required roles. Get a new key: **Unraid UI → Settings → Management Access → API Keys → Create** (select "Viewer" role for read-only, or appropriate roles for mutations).
|
|
|
|
---
|
|
|
|
## Invalid Action / Subaction
|
|
|
|
**Error:** `Invalid action 'X'` or `Invalid subaction 'X' for action 'Y'`
|
|
|
|
**Fix:** Check the domain table in `SKILL.md` for the exact `action=` and `subaction=` strings. Common mistakes:
|
|
|
|
| Wrong | Correct |
|
|
|-------|---------|
|
|
| `action="info"` | `action="system"` |
|
|
| `action="notifications"` | `action="notification"` |
|
|
| `action="keys"` | `action="key"` |
|
|
| `action="plugins"` | `action="plugin"` |
|
|
| `action="settings"` | `action="setting"` |
|
|
| `subaction="unread"` | `subaction="mark_unread"` |
|
|
|
|
---
|
|
|
|
## Destructive Action Blocked
|
|
|
|
**Error:** `Action 'X' was not confirmed. Re-run with confirm=True to bypass elicitation.`
|
|
|
|
**Fix:** Add `confirm=True` to the call:
|
|
|
|
```python
|
|
unraid(action="array", subaction="stop_array", confirm=True)
|
|
unraid(action="vm", subaction="force_stop", vm_id="<id>", confirm=True)
|
|
```
|
|
|
|
See the Destructive Actions table in `SKILL.md` for the full list.
|
|
|
|
---
|
|
|
|
## Live Subscription Returns "Connecting"
|
|
|
|
**Symptoms:** `unraid(action="live", ...)` returns `{"status": "connecting"}`
|
|
|
|
**Explanation:** The persistent WebSocket subscription has not yet received its first event. Retry in a moment.
|
|
|
|
**Known issue:** `live/array_state` uses `arraySubscription` which has a known Unraid API bug (returns null for a non-nullable field). This subscription may show "connecting" indefinitely.
|
|
|
|
**Event-driven subscriptions** (`live/parity_progress`, `live/notifications_overview`, `live/owner`, `live/server_status`, `live/ups_status`) only populate when the server emits a change event. If the server is idle, these may never populate during a session.
|
|
|
|
**Workaround for array state:** Use `unraid(action="system", subaction="array")` for a synchronous snapshot instead.
|
|
|
|
---
|
|
|
|
## Rate Limit Exceeded
|
|
|
|
**Limit:** 100 requests / 10 seconds
|
|
|
|
**Symptoms:** HTTP 429 or rate limit error
|
|
|
|
**Fix:** Space out requests. Avoid polling in tight loops. Use `live/` subscriptions for real-time data instead of polling `system/metrics` repeatedly.
|
|
|
|
---
|
|
|
|
## Log Path Rejected
|
|
|
|
**Error:** `Invalid log path`
|
|
|
|
**Valid log path prefixes:** `/var/log/`, `/boot/logs/`, `/mnt/`
|
|
|
|
Use `unraid(action="disk", subaction="log_files")` to list available logs before reading.
|
|
|
|
---
|
|
|
|
## Container Logs Not Available
|
|
|
|
Docker container stdout/stderr are **not accessible via the Unraid API**. SSH to the Unraid server and use `docker logs <container>` directly.
|