Troubleshooting
Start with the symptom and then inspect Settings → Service, the desktop error surface, or the terminal interface's Errors tab for more detail.
| Symptom | Usual meaning | What to do |
|---|---|---|
| PAIR remains on Loading... | A background service did not start correctly. | Wait one or two minutes, then inspect Settings → Service and restart the affected service. |
| A node is not discovered | mDNS is blocked or unavailable. | Confirm both nodes are on the same trusted local network, allow 5353/udp, or add the node by IP address. |
| Pairing stalls or fails | The invitation expired, the PIN is incorrect, or port 14321 is blocked. | Start a new invitation, enter the new PIN, and confirm cluster ports are reachable. |
| Connection refused | Nothing is listening at that address. | Copy the current URL from Endpoints and confirm the PAIR service is running. |
403 from another machine | PAIR endpoints accept loopback traffic only. | Run PAIR on the machine hosting the client and use its local endpoint. |
502 with no active node | No node is eligible for the request. | Start a compatible engine and make the requested model available on at least one online node. |
Persistent 404 on inference | No eligible node has the requested model. | Verify the exact model name and prepare it on at least one node. |
400 or 422 | The request is malformed. | Correct its JSON, route, model name, or required fields; malformed requests are not retried. |
| A response arrives but Jobs is empty | Another process owns the expected proxy port. | Check Endpoints and Settings → Service, then change the PAIR port or stop the conflicting process. |
| Requests do not use every GPU | PAIR routes each request to one eligible node. | Send independent requests and verify Ran on for each job. PAIR does not split one request across GPUs. |
| Desktop and terminal behavior conflicts | Both PAIR interfaces are running on one system. | Stop one interface and use only the desktop application or terminal interface. |