Route independent local AI requests across paired systems using llama.cpp, Ollama, or LM Studio
Start with the symptom and then inspect Settings → Service, the desktop error surface, or the terminal interface's Errors tab for more detail. In the terminal interface, also check Service for worker state and Logs for engine installation or startup output.
| 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. |
| llama.cpp is missing, or the terminal shows the old ten-tab layout | The installed PAIR version predates this playbook's 1.0.0 workflow. | Check the PAIR version and install the matching 1.0.0 package for your OS and architecture. |
| An installer does not match the system | The architecture choice is incorrect. | Use Windows ARM64 for RTX Spark, Linux ARM64 for DGX Spark, and macOS ARM64 for Apple silicon. Intel/AMD systems use x64 packages, named amd64 for Debian/Ubuntu. |
| LM Studio remains after uninstalling PAIR 1.0.0 | LM Studio installations created by older PAIR versions are not removed by the newer PAIR uninstaller. | If you also want to remove LM Studio, uninstall that older installation manually from ~/.lmstudio on Linux or macOS, or %USERPROFILE%\.lmstudio on Windows. |
| 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. |
| A model is listed but the inference request fails | The request's model ID, API route, or engine does not match the prepared model. | Copy the exact ID from <PAIR_BASE_URL>/v1/models. For llama.cpp, preserve owner/repository:quantization and use /v1/chat/completions, not Ollama's /api/chat. |
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. |
nvpair is not found in native Windows PowerShell | The packaged launcher has not been created or the shell has not picked up its PATH entry. | Open the installed PAIR app once, quit it, and open a new PowerShell window before running nvpair. |
| A llama.cpp model download or load fails | The GGUF selection or available resources need checking. | Confirm the selected engine is llama.cpp, choose a compatible catalog entry, and inspect Errors and Logs. Check available disk space and memory, including context overhead. |
| llama.cpp fails after custom launch arguments | A fixed-model argument can conflict with PAIR's managed router mode. | Remove custom -m or -hf arguments and use PAIR's model download and load controls. |
| A loaded llama.cpp model becomes idle and the next request takes longer | Managed llama.cpp puts idle models to sleep after five minutes and wakes them for a new request. | Allow the model to wake; inspect Jobs to confirm that the request completes. |
| A browser client reports a CORS error | PAIR 1.0.0 follows the selected engine's origin policy. | Configure the allowed browser origin on the system running that engine. For Ollama, set OLLAMA_ORIGINS in the engine's Settings launch arguments. |