> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gym.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Scale Gymnasium environments

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    |

<Tip>
  Failed checks include an `all_results` field containing all data that was searched. Use this to diagnose why expected data was not found.
</Tip>

### 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

```bash theme={null}
docker ps -a
```

Look for:

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

### 2. View Container Logs

```bash theme={null}
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     |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Docker Quick Start" icon="docker" href="/getting-started/quickstart-docker">
    Deploy environments with Docker
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Check API documentation
  </Card>
</CardGroup>