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
3.3 KiB
Unraid MCP — Troubleshooting Guide
Credentials Not Configured
Error: CredentialsNotConfiguredError or message containing ~/.unraid-mcp/.env
Fix: Run setup to configure credentials interactively:
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:
- Test basic connectivity:
unraid(action="health", subaction="test_connection")
- Full diagnostic report:
unraid(action="health", subaction="diagnose")
-
Check that
UNRAID_API_URLin~/.unraid-mcp/.envpoints to the correct Unraid GraphQL endpoint. -
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:
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.