3888b9cb4a
Thread 6: Add python language specifier to .claude-plugin/README.md code fence Thread 7: Fix MD022/MD031 spacing in docs/MARKETPLACE.md Thread 8: Blank line before Destructive Actions heading in README.md Thread 9: Move H1 to first line in skills/unraid/references/api-reference.md Thread 10+11+12: Rewrite quick-reference.md: - Fix MD022/MD031 (blank lines around headings/fences) - Add python language specifiers to all code fences - Fix disk/logs params: path/lines → log_path/tail_lines - Add path param to live/log_tail example - Remove invalid notification/unread subaction - Fix notification/list filter= → list_type= Thread 13: Add python/text language specifiers to troubleshooting.md fences Thread 14: Update test-tools.sh header comment (in separate commit) Also: Remove 'connect' from README system subactions table (it was removed from the tool in previous commit), fix notification 'unread' → 'mark_unread' in table
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.