Skip to content

troubleshooting.md

Latest commit

 

History

History
172 lines (119 loc) · 5.9 KB

troubleshooting.md

File metadata and controls

172 lines (119 loc) · 5.9 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_ACCESS_HOST and UNIFI_ACCESS_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 (proxy session)

Symptoms: 401 Unauthorized on port 443, "invalid credentials" errors.

Check:

  1. Verify UNIFI_ACCESS_USERNAME and UNIFI_ACCESS_PASSWORD are correct
  2. Ensure the account is a local admin (not a Ubiquiti SSO account)
  3. Try logging into the UniFi OS Console web UI with the same credentials
  4. Confirm the Access application is installed and running on the controller

API key auth failing (port 12445)

Symptoms: 401 on port 12445, py-unifi-access connection errors.

Check:

  1. Verify UNIFI_ACCESS_API_KEY is correct and has not been revoked
  2. Confirm port 12445 is reachable from the MCP server: curl -k https://<HOST>:12445
  3. Check that the Access application exposes port 12445 (some network configurations or Docker setups may block non-standard ports)
  4. The API key is generated from the UniFi OS Console under Settings > API Keys

Proxy session fallback

Symptoms: Some tools work but others return "proxy session required" errors.

Explanation: Most mutating tools (lock/unlock, credential management, policies, visitors) require the local proxy session (port 443 with username/password). If only the API key is configured, these tools will be unavailable.

Fix: Ensure both UNIFI_ACCESS_USERNAME/UNIFI_ACCESS_PASSWORD and UNIFI_ACCESS_API_KEY are set for full functionality.

"Access application not found" errors

Symptoms: Connection succeeds but the server reports Access is not available.

Check:

  1. Log into the UniFi OS Console and verify the Access application is installed
  2. Ensure the Access application is running (not stopped or updating)
  3. Check that your admin account has access to the Access application

SSL Issues

SSL certificate verification errors

Symptoms: SSL: CERTIFICATE_VERIFY_FAILED or similar errors.

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

export UNIFI_ACCESS_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 Access 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 access_unlock_door is missing:

export UNIFI_PERMISSIONS_DOORS_UPDATE=true

Tool returns "permission denied" via access_execute

Cause: In lazy/meta_only mode, access_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: access_recent_events returns empty results; access://events/stream resource is empty.

Check:

  1. Verify ACCESS_WEBSOCKET_ENABLED=true (default)
  2. Check server logs for websocket connection errors
  3. Ensure UNIFI_ACCESS_API_KEY is configured (websocket events may require API key auth)
  4. Verify Access devices are generating events (try unlocking a door manually)
  5. Use access_list_events to verify events exist on the controller (REST API works independently)

Events disappearing from buffer

Cause: Buffer overflow or TTL expiration.

Fix:

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

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_ACCESS_HOST plus credentials)

Cannot connect to controller from Docker

Fix options:

  1. Use --network host to share the host network stack
  2. Or ensure the Docker network can route to the controller IP
  3. Verify the controller IP is not a localhost address (use the actual network IP)
  4. For API key auth, ensure port 12445 is accessible from the container (not just port 443)

Environment variable setup for Docker

docker run -i --rm \
  -e UNIFI_ACCESS_HOST=192.168.1.1 \
  -e UNIFI_ACCESS_USERNAME=admin \
  -e UNIFI_ACCESS_PASSWORD=your-password \
  -e UNIFI_ACCESS_API_KEY=your-api-key \
  -e UNIFI_PERMISSIONS_DOORS_UPDATE=true \
  ghcr.io/sirkirby/unifi-access-mcp:latest

Or use an env file:

docker run -i --rm --env-file .env ghcr.io/sirkirby/unifi-access-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:

  • Access connection and dual-path 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).