Debug an error

Nothing is analysed until you ask. DebugAI keeps the last few terminal outputs in memory so it can read them when you do, and it never sends one on its own.

From the terminalCopy Anchor Link

Run the failing command in VS Code's integrated terminal. Then right-click inside the terminal and pick DebugAI: Analyze Terminal Error. It is also in the Command Palette, and on the Analyze error from terminal button in the results panel.

DebugAI shows what it found, as Found in terminal: "..." with the first 120 characters, and offers Analyze This, Paste My Own and Cancel.

Where it reads from, in order:

1. VS Code's shell integration. The extension keeps the output of the last 5 commands, up to 50,000 characters each, with each command's exit code. It prefers the most recent command that exited with a non-zero code and printed an error.
2. The terminal's own text. If shell integration has nothing, it selects everything in the terminal, copies it, and puts your clipboard back the way it was.

It reads the terminal, not your selection, so selecting text in the terminal first changes nothing. To send exactly the text you chose, copy it and use Paste My Own, or use DebugAI: Analyze Error below.

When there is nothing usable, it asks you to paste the error, and the prompt says why:

• No error found in the terminal, only a prompt or command output. Paste the error text:
• The terminal had nothing to read. Run the command that fails, then try again, or paste the error text:
• DebugAI could not read a terminal in this window. Paste the error text:

From the editorCopy Anchor Link

Select the error text and press Ctrl Alt D (Cmd Alt D on a Mac). That runs DebugAI: Analyze Error. The shortcut works while the editor has focus. The same command is on the editor's right-click menu and on the DebugAI item in the status bar.

What it sends depends on what is under your cursor:

• A selection longer than 5 characters that reads as an error is used as it is.
• No selection, and the line under your cursor reads as an error: it asks Use: "..." with Yes, Paste My Own and Use Terminal Error.
• Anything else opens a box to paste into: Paste error from terminal, browser (Streamlit/Flask UI), or app console:

It works with no file open too, and goes straight to the paste box.

Paste the whole stack trace, not the last line. The frames are what name the files DebugAI should read.

A file outside a projectCopy Anchor Link

If the file you are in is not inside an open folder, DebugAI says so once per window: DebugAI is reading this file on its own. Open the containing folder and it can index your project, trace errors across files, and remember fixes for this codebase. Press Open Folder to fix it. Without a folder there is no project to index or remember.

Warnings in the Problems panelCopy Anchor Link

After an analysis, DebugAI marks up to three of the lines the error names with a warning, [DebugAI] Root cause: and the start of the answer. Only lines in files that are inside your workspace and open in an editor get one. Their quick fix, Fix with DebugAI, runs DebugAI: Analyze Error again. The marks are replaced by the next analysis.

A failing testCopy Anchor Link

There is no test runner integration, and DebugAI does not run your tests. Run the test in the integrated terminal and use DebugAI: Analyze Terminal Error, or paste the output into DebugAI: Analyze Error. DebugAI reads test output for the files in it, including pytest's FAILED tests/x.py::test_y summary lines and the stack frames a JavaScript test runner prints, so a test failure is traced like any other error.

What one debug sendsCopy Anchor Link

One request to POST /api/debug, over HTTPS:

• the error text, cut to 3,000 characters with the start and the end kept;
• the code around your cursor, up to 30 lines on each side and 50,000 characters, with the line number it starts on;
• the language, the path of the file you are in, and a framework hint read from your manifests;
• project facts: dependency names and versions, which manifests exist, Python module names, whether a virtual environment or node_modules exists, and the selected Python interpreter path;
• a project id, which is an md5 hash of your first workspace folder's path;
• the extension's version.

Nothing about your git repository goes with a debug. Indexed files are already on the server, so they are not sent again. More in What leaves your machine.

Two guards hold back the code, and the error text is still sent. If the file you are in looks like it holds credentials, the status bar shows for 8 seconds:

DebugAI: the code around your cursor was not sent, because this file looks like it holds credentials. The error text was.

If the 61 lines around your cursor contain the first or last line of a private key:

DebugAI: the code around your cursor was not sent, because it contains a private key. The error text was.

While it runsCopy Anchor Link

A notification says DebugAI analyzing your error… or DebugAI analyzing terminal error…, and the status bar shows DebugAI analyzing.... The extension waits up to 110 seconds for an answer. Past that you get DebugAI: The engine did not answer within 110 seconds. It may be busy. with Retry.

Before you sign in, the editor command answers DebugAI: not connected yet. Sign in for 10 free debugs a day, no card. with Sign in → and I Have a Key, and the terminal command answers DebugAI: No API key set. with Set API Key.

Text that is not an errorCopy Anchor Link

Send a terminal prompt, a block of source code, or a DebugAI answer, and DebugAI says so instead of inventing a diagnosis. The root cause is one line, for example That is a terminal prompt, not an error message., That is source code, not an error. or No error message was found in that text., and the only fix is Paste the error itself, at 0%.

That attempt is not counted against your daily limit. Sending the same text again gets the same answer, so change what you paste instead of retrying.

NextCopy Anchor Link

• Read a result: what each part of the panel tells you.
• Apply and undo a fix.
• The answer says Insufficient context for specific fix: see Read a result and Index your project.