efaab031ae
Resolves review threads: - PRRT_kwDOO6Hdxs50fewG (setup.py): non-eliciting clients now return True from elicit_reset_confirmation so they can reconfigure without being blocked - PRRT_kwDOO6Hdxs50fewM (test-tools.sh): add notification/recalculate smoke test - PRRT_kwDOO6Hdxs50fewP (test-tools.sh): add system/array smoke test - PRRT_kwDOO6Hdxs50fewT (resources.py): surface manager error state instead of reporting 'connecting' for permanently failed subscriptions - PRRT_kwDOO6Hdxs50feAj (resources.py): use is not None check for empty cached dicts - PRRT_kwDOO6Hdxs50fewY (integration tests): remove duplicate snapshot-registration tests already covered in test_resources.py - PRRT_kwDOO6Hdxs50fewe (test_resources.py): replace brittle import-detail test with behavior tests for connecting/error states - PRRT_kwDOO6Hdxs50fewh (test_customization.py): strengthen public_theme assertion - PRRT_kwDOO6Hdxs50fewk (test_customization.py): strengthen theme assertion - PRRT_kwDOO6Hdxs50fewo (__init__.py): correct subaction count ~88 -> ~107 - PRRT_kwDOO6Hdxs50fewx (test_oidc.py): assert providers list value directly - PRRT_kwDOO6Hdxs50fewz (unraid.py): remove unreachable raise after vm handler - PRRT_kwDOO6Hdxs50few2 (unraid.py): remove unreachable raise after docker handler - PRRT_kwDOO6Hdxs50fev8 (CLAUDE.md): replace legacy 15-tool table with unified unraid action/subaction table - PRRT_kwDOO6Hdxs50fev_ (test_oidc.py): assert providers + defaultAllowedOrigins - PRRT_kwDOO6Hdxs50feAz (CLAUDE.md): update tool categories to unified API shape - PRRT_kwDOO6Hdxs50feBE (CLAUDE.md/setup.py): update unraid_health refs to unraid(action=health, subaction=setup)
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 will always show "connecting."
Event-driven subscriptions (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.