Merge pull request #2688 from yueguobin/fix/llm-model-config-error-message

fix: include error details in LLM model config + docs: add troubleshooting guides

docs/features/compute-controller-setup.md

@@ -71,8 +71,10 @@ POST /v3/computes
 
 ### Host Configuration
 
-- **Controller `host`**: If set to `0.0.0.0`, it will be changed to `127.0.0.1`, which breaks cross-subnet link creation
-- **Solution**: Always use the actual IP address for Controller's `host` field
+- **Controller `host`**: If set to `0.0.0.0`, the controller will register itself as `127.0.0.1`, which breaks remote compute connections
+- **Symptom**: Compute nodes report "No common subnet for compute X (controller) and Y" even when on the same network
+- **Solution**: Always use the actual LAN IP address for the Controller's `host` field (e.g., `host = 192.168.1.104`)
+- **Dynamic IP**: If the controller machine uses DHCP, set a static lease on the router or use mDNS (`.local` domain)
 
 ### Password Configuration
 
@@ -99,6 +101,46 @@ POST /v3/computes
 
 ### No Common Subnet Error
 
-1. Verify Controller's `host` is set to its actual IP, not `0.0.0.0`
-2. Ensure both machines are on the same network
-3. Check firewall rules allow UDP communication
+If compute nodes report:
+```
+Cannot get an IP address on same subnet: No common subnet for compute X (controller) and Y
+```
+
+1. **Primary cause**: Controller's `host` is set to `0.0.0.0` - it registers as `127.0.0.1` which is unreachable from compute nodes
+2. Check the controller's `/v3/version` endpoint - if `controller_host` shows `127.0.0.1`, this is the issue
+3. Set the Controller's `host` to its actual LAN IP address (e.g., `192.168.1.104`)
+4. Verify both machines are on the same network and can ping each other
+5. Check firewall rules allow TCP/UDP communication on required ports
+
+### WebSocket Console Authentication Failed
+
+When connecting to a remote compute node's console via WebSocket, the connection may fail with errors in the logs:
+
+**Controller log:**
+```
+New client 192.168.1.104:33268 has connected to controller console WebSocket
+Forwarding console WebSocket to 'ws://192.168.1.3:3080/v3/compute/projects/.../console/ws'
+Client 192.168.1.104:33268 has disconnected from controller console WebSocket
+```
+
+**Compute log:**
+```
+WebSocket /v3/compute/projects/.../console/ws" [accepted]
+ERROR gns3server.api.routes.compute.dependencies.authentication:103 Could not authenticate while connecting to compute WebSocket: Could not validate credentials
+```
+
+**Cause**: The Controller forwards its own `compute_username` and `compute_password` credentials when connecting to the Compute's WebSocket endpoint. If the Compute node does not have matching credentials configured, authentication fails.
+
+**Solution**: Ensure the Compute node's configuration file has matching credentials:
+
+```ini
+[Server]
+enable_http_auth = True
+compute_username = gns3
+compute_password = your_password
+```
+
+The Controller automatically uses its configured `compute_username` and `compute_password` when establishing WebSocket connections to remote computes (see `gns3server/api/routes/controller/nodes.py` lines 627-628).
+
+**Note**: If `compute_password` is not explicitly set in the Compute's config, a random 16-character password is auto-generated at startup, making authentication impossible for any external Controller.
+

gns3server/api/routes/controller/llm_model_configs.py

@@ -242,7 +242,7 @@ async def create_user_llm_model_config(
         log.error(f"Failed to create LLM model config: {e}")
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="Failed to create LLM model configuration"
+            detail=f"Failed to create LLM model configuration: {e}"
         )
 
 
@@ -564,7 +564,7 @@ async def create_group_llm_model_config(
         log.error(f"Failed to create LLM model config: {e}")
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="Failed to create LLM model configuration"
+            detail=f"Failed to create LLM model configuration: {e}"
         )