> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/working-with-ai-agents/debugging-with-ai.md).

# Debugging with AI

Use this process when something in Sandbox Studio behaves differently than expected, throws an error, or stops working after a change. The goal is to give the AI enough evidence to reason about the problem without guessing.

## Step 1: Capture the problem

Write one sentence that names the broken behavior.

1. State what you expected to happen.
2. State what happened instead.
3. Name the feature, scene, node, or UI involved.

Example: When I press E near the door, the indicator disappears but the door does not open.

## Step 2: Reproduce the issue

Trigger the problem again from a known starting point.

1. Open the scene or project state where the issue happens.
2. Perform the exact action that causes the issue.
3. Confirm whether the same result happens again.

The broken behavior is visible after completing the reproduction steps.

{% hint style="info" %}
*TIP: If the issue does not happen again, write down what changed before continuing.*
{% endhint %}

## Step 3: Collect the evidence

Open the browser console and save the output as a file. This gives the AI the exact error trace without any transcription errors on your part.

1. Press F12 to open the browser console. The DevTools panel opens at the bottom or side of the window.
2. Click the Console tab if it is not already selected. Look for red error messages or yellow warnings.
3. Right-click anywhere in the console output and choose Save as... to save the log as a file.
4. Drop the saved file directly into the agent chat window. The AI reads the full log without you needing to copy or summarize anything.

{% hint style="info" %}
*TIP: If the console is empty, reproduce the issue first, then save. The log only captures what has run in the current session.*
{% endhint %}

## Step 4: Give the AI the context

Send the AI a short debugging brief before asking for a fix.

1. Describe what you were trying to build.
2. Describe the current behavior and desired behavior.
3. Paste the exact error or symptom and list the relevant files, nodes, or UI.

Use this prompt pattern: I was trying to \[goal]. I expected \[result]. Instead \[actual behavior]. Here is the exact error: \[error]. The relevant project context is \[files or objects].

## Step 5: Ask for likely causes

Ask the AI to explain the most likely causes before changing anything.

1. Request two or three likely causes.
2. Ask what evidence supports each cause.
3. Ask which cause should be checked first.

Example prompt: Given this error and context, list the three most likely causes. Do not edit anything yet. Tell me what evidence supports each cause.

{% hint style="info" %}
*TIP: If the AI jumps straight to a fix, ask it to pause and explain the reasoning first.*
{% endhint %}

## Step 6: Apply one fix

Choose the smallest fix that matches the evidence and apply only that fix.

1. Keep the change limited to the files needed for the chosen fix.
2. Avoid combining several possible fixes in one pass.
3. Stop after the focused change is made.

{% hint style="danger" %}
*WARNING: Do not delete files, reset work, or remove unrelated systems to clear an error unless you understand the effect and have a safe version control checkpoint.*
{% endhint %}

## Step 7: Run the same check

Repeat the same reproduction steps you used before the fix.

1. Start from the same scene or project state.
2. Perform the same action that caused the issue.
3. Compare the new result with the original problem.

{% hint style="info" %}
*TIP: If the issue changes, give the AI the new behavior and continue from Step 3. A changed symptom is useful evidence.*
{% endhint %}

## Step 8: Share the result

Tell the AI what happened after the check.

1. Say whether the original issue is fixed.
2. Paste any new error message or behavior.
3. Ask for the next smallest step if the issue remains.

Example: After this change, the Indicator appears again, but pressing E still does not open the door.

## Step 9: Record the fix

Write a short note explaining the symptom, cause, and final change.

1. Name the original symptom.
2. Name the cause if it is known.
3. Name the change that fixed it.

Keep this note with the task, project notes, or pull request so the same problem is easier to recognize later.

## What You've Done

You have turned a vague problem into a focused debugging loop: reproduce the issue, collect evidence, ask the AI for likely causes, apply one fix, and verify the result. Use the same process whenever a Sandbox Studio feature behaves differently than expected.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/working-with-ai-agents/debugging-with-ai.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.