Troubleshooting Sandboxes
Check project configuration, permissions, lifecycle state, and network access when sandbox operations fail.
| Issue | What to check |
|---|---|
| CLI command or SDK class is missing | Use an OCI CLI or SDK version that includes the Sandbox API. Check oci generative-ai-sandbox --help. |
| Sandbox creation fails | Check project sandbox enablement, project state, selected region, IAM permissions, and available capacity. The project must be active. |
| Custom-network project creation fails | Verify the subnet OCID, region, caller permissions, and NSGs. Supply at most five unique NSGs in the subnet's VCN. Inspect work requests and lifecycle details if the project fails. |
| A custom image fails validation or can't be pulled | Check the full image URI, image region, repository permissions, and any required vulnerability scan results. |
| A sandbox can't reach a destination | For managed networking, check the network policy and permitted domains. For custom networking, check DNS, routes, security lists, NSGs, and gateway or private connectivity. |
| A command fails or times out | Inspect standard error and the exit code. Check the command, installed dependencies, working paths, command timeout, and remaining sandbox lifetime. |
| A published service can't be reached | Confirm that the sandbox is running, the port was published at creation, and the service is ready and listening on the published port on an externally reachable interface such as 0.0.0.0. |
| Extend or Stop is unavailable | Check whether the sandbox has already stopped or expired. Use a new sandbox for another execution session. A file system snapshot can supply saved files. |
| A metric chart is empty | Select a time range that includes sandbox activity. See Monitoring Sandboxes. |
| No warm pools are listed | A project can have no warm pools. Check the selected project and the status of any pool creation operation. See Warm Pools for Sandboxes. |
When requesting help, record the operation, request identifier, region, project and sandbox identifiers, and relevant error messages. Remove secrets and sensitive command output from shared diagnostic information.