This guide covers common error scenarios and solutions for each Scale Gymnasium environment.
Website Environment Issues
Verifier Errors
| Error Type | HTTP Status | Common Causes |
|---|
| ValidationError | 400 | Invalid check patterns, missing required fields, malformed structure |
| ExecutionError | 500 | Database connection failure, SQL syntax error, function not found |
Failed checks include an all_results field containing all data that was searched. Use this to diagnose why expected data was not found.
Session Errors
| Issue | Solution |
|---|
| Session not found | Call /api/reset with a valid sessionId first |
| Data pack not found | Verify the data pack name is correct |
| Stale data | Call /api/reset to reinitialize the session |
| Cross-session contamination | Ensure unique sessionId per test |
State Not Updating
| Issue | Solution |
|---|
| Changes not visible | Refresh state query after action completes |
| Wrong session | Verify sessionId matches across all calls |
| Transaction pending | Wait for previous operation to complete |
MCP Environment Issues
| Issue | Solution |
|---|
| Tool not found | Verify exact tool name (case-sensitive) |
| Invalid parameters | Check parameter types against schema |
| Missing required params | Review tool’s input schema |
| Wrong server | Ensure tool exists on expected server |
Session Isolation
| Issue | Solution |
|---|
| Data not persisting | Use consistent tags across calls |
| Wrong data returned | Verify session/assignment ID |
| State reset unexpectedly | Check for unintended reset calls |
Server Errors
| Issue | Solution |
|---|
| Server unavailable | Verify MCP container is running |
| Connection timeout | Check network connectivity |
| Internal server error | Review server logs for details |
Desktop Environment Issues
VM Lifecycle Errors
| Issue | Solution |
|---|
| VM creation failed | Check resource quotas and availability |
| Initialization failed | Verify initialization script syntax |
| Evaluator failed | Check gold standard file paths |
| VM unresponsive | Reset and try again |
Access Errors
| Issue | Solution |
|---|
| noVNC not accessible | Verify authentication and port 8006 |
| OSWorld API unreachable | Check port 5000 connectivity |
| VNC connection refused | Verify port 5900 is exposed |
| Black screen | Wait for VM boot, then retry |
Screenshot Issues
| Issue | Solution |
|---|
| Empty screenshot | Wait for UI to render |
| Stale screenshot | Capture after action completes |
| Low quality | Check display settings |
Docker Issues
Image Problems
| Issue | Solution |
|---|
| Image not found | Run docker load -i <file>.tar |
| Load failed | Verify tar file is not corrupted |
| Wrong version | Check image tag matches expected |
Container Problems
| Issue | Solution |
|---|
| Won’t start | Check port conflicts with docker ps |
| Exits immediately | View logs with docker logs <container> |
| Permission denied | Verify Docker daemon access |
| Out of memory | Increase Docker memory allocation |
Network Problems
| Issue | Solution |
|---|
| Connection refused | Verify container is running and port is exposed |
| Timeout | Check firewall rules |
| DNS issues | Use localhost or 127.0.0.1 instead of hostnames |
Common Debugging Steps
1. Check Container Status
Look for:
- Container is running (not exited)
- Correct port mappings
- Container age (recently restarted?)
2. View Container Logs
docker logs <container_id>
- Error messages
- Stack traces
- Startup issues
Getting Help
If issues persist, contact Scale support with:
| Information | Why It Helps |
|---|
| Environment type | Directs to right team |
| Error messages | Identifies specific issue |
| Steps to reproduce | Enables debugging |
| Docker logs | Shows container state |
| Request/response | Shows API interaction |
Next Steps
