forked from HomeLab/unraid-mcp
37e9424a5c
Comprehensive fixes across Python code, shell scripts, and documentation addressing all remaining MEDIUM and LOW priority review comments. Python Code Fixes (27 fixes): - tools/info.py: Simplified dispatch with lookup tables, defensive guards, CPU fallback formatting, !s conversion flags, module-level sync assertion - tools/docker.py: Case-insensitive container ID regex, keyword-only confirm, module-level ALL_ACTIONS constant - tools/virtualization.py: Normalized single-VM dict responses, unified list/details queries - core/client.py: Fixed HTTP client singleton race condition, compound key substring matching for sensitive data redaction - subscriptions/: Extracted SSL context creation to shared helper in utils.py, replaced deprecated ssl._create_unverified_context API - tools/array.py: Renamed parity_history to parity_status, hoisted ALL_ACTIONS - tools/storage.py: Fixed dict(None) risks, temperature 0 falsiness bug - tools/notifications.py, keys.py, rclone.py: Fixed dict(None) TypeError risks - tests/: Fixed generator type annotations, added coverage for compound keys Shell Script Fixes (13 fixes): - dashboard.sh: Dynamic server discovery, conditional debug output, null-safe jq, notification count guard order, removed unused variables - unraid-query.sh: Proper JSON escaping via jq, --ignore-errors and --insecure CLI flags, TLS verification now on by default - validate-marketplace.sh: Removed unused YELLOW variable, defensive jq, simplified repository URL output Documentation Fixes (24+ fixes): - Version consistency: Updated all references to v0.2.0 across pyproject.toml, plugin.json, marketplace.json, MARKETPLACE.md, __init__.py, README files - Tool count updates: Changed all "26 tools" references to "10 tools, 90 actions" - Markdown lint: Fixed MD022, MD031, MD047 issues across multiple files - Research docs: Fixed auth headers, removed web artifacts, corrected stale info - Skills docs: Fixed query examples, endpoint counts, env var references All 227 tests pass, ruff and ty checks clean.
37 lines
1.5 KiB
Markdown
37 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
|