Troubleshooting

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

Tool Call Errors

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

docker ps -a

Look for:

Container is running (not exited)
Correct port mappings
Container age (recently restarted?)

2. View Container Logs

docker logs <container_id>

Look for:

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

Overview

Getting Started

Deep Dives

Website Environment Issues

Verifier Errors

Session Errors

State Not Updating

MCP Environment Issues

Tool Call Errors

Session Isolation

Server Errors

Desktop Environment Issues

VM Lifecycle Errors

Access Errors

Screenshot Issues

Docker Issues

Image Problems

Container Problems

Network Problems

Common Debugging Steps

1. Check Container Status

2. View Container Logs

Getting Help

Next Steps

Docker Quick Start

API Reference

​Website Environment Issues

​Verifier Errors

​Session Errors

​State Not Updating

​MCP Environment Issues

​Tool Call Errors

​Session Isolation

​Server Errors

​Desktop Environment Issues

​VM Lifecycle Errors

​Access Errors

​Screenshot Issues

​Docker Issues

​Image Problems

​Container Problems

​Network Problems

​Common Debugging Steps

​1. Check Container Status

​2. View Container Logs

​Getting Help

​Next Steps

Docker Quick Start

API Reference

Website Environment Issues

Verifier Errors

Session Errors

State Not Updating

MCP Environment Issues

Tool Call Errors

Session Isolation

Server Errors

Desktop Environment Issues

VM Lifecycle Errors

Access Errors

Screenshot Issues

Docker Issues

Image Problems

Container Problems

Network Problems

Common Debugging Steps

1. Check Container Status

2. View Container Logs

Getting Help

Next Steps