mirror of
https://github.com/jmagar/unraid-mcp.git
synced 2026-03-02 00:04:45 -08:00
184b8aca1c
**Critical Fixes (7 issues):**
- Fix GraphQL schema field names in users tool (role→roles, remove email)
- Fix GraphQL mutation signatures (addUserInput, deleteUser input)
- Fix dict(None) TypeError guards in users tool (use `or {}` pattern)
- Fix FastAPI version constraint (0.116.1→0.115.0)
- Fix WebSocket SSL context handling (support CA bundles, bool, and None)
- Fix critical disk threshold treated as warning (split counters)
**High Priority Fixes (11 issues):**
- Fix Docker update/remove action response field mapping
- Fix path traversal vulnerability in log validation (normalize paths)
- Fix deleteApiKeys validation (check response before success)
- Fix rclone create_remote validation (check response)
- Fix keys input_data type annotation (dict[str, Any])
- Fix VM domain/domains fallback restoration
**Changes by file:**
- unraid_mcp/tools/docker.py: Response field mapping
- unraid_mcp/tools/info.py: Split critical/warning counters
- unraid_mcp/tools/storage.py: Path normalization for traversal protection
- unraid_mcp/tools/users.py: GraphQL schema + null handling
- unraid_mcp/tools/keys.py: Validation + type annotations
- unraid_mcp/tools/rclone.py: Response validation
- unraid_mcp/tools/virtualization.py: Domain fallback
- unraid_mcp/subscriptions/manager.py: SSL context creation
- pyproject.toml: FastAPI version fix
- tests/*: New tests for all fixes
**Review threads resolved:**
PRRT_kwDOO6Hdxs5uu70L, PRRT_kwDOO6Hdxs5uu70O, PRRT_kwDOO6Hdxs5uu70V,
PRRT_kwDOO6Hdxs5uu70e, PRRT_kwDOO6Hdxs5uu70i, PRRT_kwDOO6Hdxs5uu7zn,
PRRT_kwDOO6Hdxs5uu7z_, PRRT_kwDOO6Hdxs5uu7sI, PRRT_kwDOO6Hdxs5uu7sJ,
PRRT_kwDOO6Hdxs5uu7sK, PRRT_kwDOO6Hdxs5uu7Tk, PRRT_kwDOO6Hdxs5uu7Tn,
PRRT_kwDOO6Hdxs5uu7Tr, PRRT_kwDOO6Hdxs5uu7Ts, PRRT_kwDOO6Hdxs5uu7Tu,
PRRT_kwDOO6Hdxs5uu7Tv, PRRT_kwDOO6Hdxs5uu7Tw, PRRT_kwDOO6Hdxs5uu7Tx
All tests passing.
Co-authored-by: docker-fixer <agent@pr-fixes>
Co-authored-by: info-fixer <agent@pr-fixes>
Co-authored-by: storage-fixer <agent@pr-fixes>
Co-authored-by: users-fixer <agent@pr-fixes>
Co-authored-by: config-fixer <agent@pr-fixes>
Co-authored-by: websocket-fixer <agent@pr-fixes>
Co-authored-by: keys-rclone-fixer <agent@pr-fixes>
Co-authored-by: vm-fixer <agent@pr-fixes>
35 lines
1.5 KiB
Markdown
35 lines
1.5 KiB
Markdown
# Unraid API Troubleshooting Guide
|
|
|
|
Common issues and solutions when working with the Unraid GraphQL API.
|
|
|
|
## "Cannot query field" error
|
|
Field name doesn't exist in your Unraid version. Use introspection to find valid fields:
|
|
```bash
|
|
./scripts/unraid-query.sh -q "{ __type(name: \"TypeName\") { fields { name } } }"
|
|
```
|
|
|
|
## "API key validation failed"
|
|
- Check API key is correct and not truncated
|
|
- Verify key has appropriate permissions (use "Viewer" role)
|
|
- Ensure URL includes `/graphql` endpoint (e.g. `http://host/graphql`)
|
|
|
|
## Empty results
|
|
Many queries return empty arrays when no data exists:
|
|
- `docker.containers` - No containers running
|
|
- `vms` - No VMs configured (or VM service disabled)
|
|
- `notifications` - No active alerts
|
|
- `plugins` - No plugins installed
|
|
|
|
This is normal behavior, not an error. Ensure your scripts handle empty arrays gracefully.
|
|
|
|
## "VMs are not available" (GraphQL Error)
|
|
If the VM manager is disabled in Unraid settings, querying `{ vms { ... } }` will return a GraphQL error.
|
|
**Solution:** Check if VM service is enabled before querying, or use error handling (like `IGNORE_ERRORS=true` in dashboard scripts) to process partial data.
|
|
|
|
## URL connection issues
|
|
- Use HTTPS (not HTTP) for remote access if configured
|
|
- For local access: `http://unraid-server-ip/graphql`
|
|
- For Unraid Connect: Use provided URL with token in hostname
|
|
- Use `-k` (insecure) with curl if using self-signed certs on local HTTPS
|
|
- Use `-L` (follow redirects) if Unraid redirects HTTP to HTTPS
|