Skip to content

troubleshooting.md

Latest commit

 

History

History
175 lines (119 loc) · 5.5 KB

troubleshooting.md

File metadata and controls

175 lines (119 loc) · 5.5 KB
Raw

Troubleshooting

Connection Issues

Cannot connect to controller

Symptoms: Connection timeout, refused, or "cannot reach host" errors.

Check:

  1. Verify the controller is reachable: curl -k https://<UNIFI_HOST>:<UNIFI_PORT>
  2. Confirm UNIFI_HOST and UNIFI_PORT are correct
  3. If using Docker, ensure the container can reach the controller (use --network host or the correct Docker network)
  4. Check firewall rules between the MCP server and the controller

Authentication failures

Symptoms: 401 Unauthorized, "invalid credentials" errors.

Check:

  1. Verify UNIFI_USERNAME and UNIFI_PASSWORD are correct
  2. Ensure the account is a local admin (not a Ubiquiti SSO account)
  3. Try logging into the Protect web UI with the same credentials
  4. The uiprotect library requires local authentication -- cloud-only accounts will not work

"ProtectApiError" or unexpected API responses

Symptoms: Tools return errors mentioning uiprotect or ProtectApiError.

Check:

  1. Ensure the controller is running UniFi OS with Protect application installed
  2. Verify the Protect application is running (not stopped or updating)
  3. Check that the user account has access to the Protect application
  4. Ensure the NVR firmware is reasonably current (uiprotect targets recent firmware versions)

SSL Issues

SSL certificate verification errors

Symptoms: SSL: CERTIFICATE_VERIFY_FAILED or similar errors.

Fix: Set UNIFI_VERIFY_SSL=false (most UniFi controllers use self-signed certificates).

export UNIFI_VERIFY_SSL=false

This is the default, so this error typically only occurs if you explicitly set it to true.

Missing Tools

Tool not appearing in client tool list

Cause: The tool's permission is disabled. All Protect mutation tools are disabled by default.

Fix:

  1. Check permissions.md for the relevant category
  2. Enable via environment variable: 
    export UNIFI_PERMISSIONS_<CATEGORY>_<ACTION>=true
  3. Restart the server

Example: If protect_update_camera_settings is missing:

export UNIFI_PERMISSIONS_CAMERAS_UPDATE=true

Tool returns "permission denied" via protect_execute

Cause: In lazy/meta_only mode, protect_tool_index shows all tools (from the static manifest), but disabled tools return permission errors when called.

Fix: Same as above -- enable the permission and restart.

No tools visible at all

Check:

  1. Verify the server started successfully (check stderr logs)
  2. Confirm your MCP client is connected
  3. Try UNIFI_TOOL_REGISTRATION_MODE=eager to load all tools immediately
  4. Check if UNIFI_ENABLED_CATEGORIES or UNIFI_ENABLED_TOOLS is set and limiting the tools

Event Streaming Issues

No real-time events in buffer

Symptoms: protect_recent_events returns empty results; protect://events/stream resource is empty.

Check:

  1. Verify PROTECT_WEBSOCKET_ENABLED=true (default)
  2. Check server logs for websocket connection errors
  3. Ensure the NVR has cameras generating events (try triggering motion manually)
  4. Use protect_list_events to verify events exist on the NVR (REST API works independently)

Events disappearing from buffer

Cause: Buffer overflow or TTL expiration.

Fix:

  • Increase PROTECT_EVENT_BUFFER_SIZE (default 100) for high-traffic environments
  • Increase PROTECT_EVENT_BUFFER_TTL (default 300 seconds) if you poll less frequently
  • Poll more frequently (every 2-5 seconds) to process events before they expire

Smart detections missing

Cause: Minimum confidence filter is too high.

Fix: Lower PROTECT_SMART_DETECTION_MIN_CONFIDENCE (default 50):

export PROTECT_SMART_DETECTION_MIN_CONFIDENCE=25

Or pass min_confidence parameter directly to protect_list_smart_detections or protect_recent_events.

Snapshot Issues

Snapshot returns error or empty data

Check:

  1. Verify the camera is connected and online (protect_list_cameras)
  2. Ensure the camera supports snapshots (most do, but some may be in a degraded state)
  3. Try fetching via the tool (protect_get_snapshot) with include_image=true
  4. Check server logs for specific error messages

HTTP Transport Issues

HTTP endpoint not starting

Check:

  1. Verify UNIFI_MCP_HTTP_ENABLED=true is set
  2. If not running as PID 1 (non-container), set UNIFI_MCP_HTTP_FORCE=true
  3. Check that port 3001 is not already in use (or change UNIFI_MCP_PORT)

Docker Issues

Container exits immediately

Check:

  1. Ensure -i flag is set (stdin must be open for stdio transport)
  2. Check logs: docker logs <container>
  3. Verify all required env vars are set (UNIFI_HOST, UNIFI_USERNAME, UNIFI_PASSWORD)

Cannot connect to NVR from Docker

Fix options:

  1. Use --network host to share the host network stack
  2. Or ensure the Docker network can route to the NVR IP
  3. Verify the NVR IP is not a localhost address (use the actual network IP)

"ModuleNotFoundError" in Docker

Cause: Usually a build issue.

Fix: Pull the latest image:

docker pull ghcr.io/sirkirby/unifi-protect-mcp:latest

Debug Logging

Enable verbose logging to diagnose issues:

export UNIFI_MCP_LOG_LEVEL=DEBUG
export UNIFI_MCP_DIAGNOSTICS=true

This outputs detailed information about:

  • Protect connection and authentication
  • WebSocket connection state
  • Permission decisions
  • Tool registration
  • API requests and responses (redacted)
  • Tool call timing

All logs go to stderr (stdout is reserved for MCP JSON-RPC in stdio mode).