Index your project
Let DebugAI read your project once, so an answer can name the file that broke and not only the file that crashed.
An error points at the line that crashed. The line that is wrong is often somewhere else: a setting, a helper, the code that built the bad value. The index is how DebugAI reads those files. Without one, it sees the error and the code around your cursor, and an answer about another file is a guess.
Start the first index yourself
Signing in does not start an index. The DebugAI connected message that appears after sign-in has an Index workspace button: press it. If the message is gone, open the Command Palette (Ctrl Shift P, or Cmd Shift P on a Mac) and run DebugAI: Index Entire Workspace. Skip both and the first index waits until VS Code next starts.
While it runs, the status bar shows DebugAI indexing... with a percentage, and the count of files sent so far. When it ends, a message says what the server stored (see When it finishes).
You'll know it worked when
The closing message starts with Indexed and a number, and DebugAI: Check Index Status answers DebugAI: N files indexed. Ready for errors.
After that it runs on its own
While the debugai.autoIndex setting is on, which it is by default, DebugAI indexes:
- the whole project once, each time VS Code starts with you signed in;
- each file again when you open or save it, if the file is inside your workspace.
An automatic full index is skipped when one finished for this project in the last 15 minutes. Running DebugAI: Index Entire Workspace yourself always runs.
The first automatic index shows this notice once per install, with Turn off auto-index and Privacy policy buttons:
DebugAI is indexing this project so answers can point at the right files. It sends the text of your source and config files to DebugAI's servers, up to 50 KB each and up to 500 files per run on any plan (Free keeps 200), and files you open or save are sent again. .env files and key files are never sent. You can turn this off with the debugai.autoIndex setting.Turn automatic indexing off
Press Turn off auto-index on that notice, or set debugai.autoIndex to false in Settings. Nothing is indexed after that unless you ask: DebugAI: Index Entire Workspace, DebugAI: Index Current File, or a Proactive Scan, which indexes the files it picks whatever the setting says.
When it finishes
The message only counts what the server confirmed it stored.
| Message | What it means |
|---|---|
Indexed N files. DebugAI can now trace an error across your codebase. | Done. Every file found was stored. |
DebugAI indexed N files so far. The remaining M are queued for the next run in about 15 minutes. Debugging works now; answers get better once the rest lands. | The server asked DebugAI to slow down partway. Press Finish indexing later, or let the next automatic run pick them up. |
DebugAI indexed N files. M more in this project were not indexed, so answers that need them will be incomplete. Nothing failed and there is nothing to retry. | The plan's file cap was reached. The free plan keeps 200 files per project. |
DebugAI: indexed N files. M could not be indexed and were not checked. Run indexing again to retry them. | Some files failed on the way. Run DebugAI: Index Entire Workspace again. |
DebugAI: The server asked us to slow down before anything was stored. Nothing was indexed. Try again in about 15 minutes. | Rate limited before the first file was stored. Run it again later. |
DebugAI: No files could be indexed. This is not a result about your codebase. | Every file failed, so nothing was stored. Press Try again. |
DebugAI: No files were indexed. | Nothing was stored, for no reason the server named. |
Two more come only from the command, when it had nothing to send:
DebugAI found no files to index in this workspace. It indexes source files such as .py, .ts, .js, .java and .cs, and leaves out folders like node_modules and dist.DebugAI could not search this workspace for files, so nothing was indexed. Run "DebugAI: Index Entire Workspace" to try again.
With no folder open, the command does nothing at all. Open your project folder first (File, Open Folder). Before you sign in, it answers DebugAI: Set your API key first.
View Details on the closing message opens the DebugAI Indexing output panel: the count, a note on any files left out or queued, and every stored file under Files indexed:.
The welcome panel
The first index of a project opens a panel headed DebugAI has read your codebase. It lists up to eight of the files it stored, says how many could not be indexed this run if any, and offers a Proactive Scan of them under Try it on your own code (Scan my code or Not now).
It opens once per project. It does not open when nothing was stored or no folder is open, and the debugai.showWelcome setting turns it off.
Index one file
DebugAI: Index Current File sends the file in the active editor. It answers with one of:
DebugAI: File indexed.DebugAI: this file is queued and will index on the next run, in about 15 minutes.DebugAI: could not index this file.DebugAI: this file was not indexed. Secret files are never indexed, and free plans cap the project at 200 files.
With no file open in an editor, it does nothing.
Check what is indexed
DebugAI: Check Index Status answers with one of:
DebugAI: N files indexed. Ready for errors.DebugAI: Indexing in progress (n/t files, p%)...DebugAI has not indexed this workspace in this window yet. Run "DebugAI: Index Entire Workspace" to index it now.DebugAI: Set your API key to start indexing. Run "DebugAI: Set API Key" from the command palette.DebugAI: No workspace open. Open a folder to begin indexing.
It reports on this VS Code window. An index from an earlier session is still on the server, so "not indexed in this window yet" does not mean your project has never been indexed.
What is indexed
- Source files ending in
.js.jsx.ts.tsx.py.mjs.cjs.java.cs. - Config files with these exact names:
Dockerfile,Makefile,package.json,tsconfig.json,jsconfig.json,pyproject.toml,requirements.txt,setup.cfg,Pipfile,pom.xml,build.gradle,build.gradle.kts,settings.gradle,go.mod,cargo.toml,nginx.conf,firebase.json,vercel.json,netlify.toml,railway.json. - Any
*.csprojfile, andDockerfile.*variants such asDockerfile.prod. - A file you open or save that VS Code treats as JavaScript, TypeScript, Python, JavaScript React or TypeScript React, whatever its extension, unless its name is on the list below.
What is never indexed
- The
.envfamily:.env,.env.local,staging.env,env.production. A module named env, such asenv.tsorenv.py, is source and is indexed. - Key and certificate files:
.pem.key.pfx.p12.jks.keystore.ppk.asc.gpg.kdbx.crt.cer.der.cert.secret. - Files whose whole name before the extension is a credential store word:
secret,secrets,credential,credentials,password,passwords,passwd,pwd,serviceaccount,service_account,service-account. Sosecrets.pyis left out andreset_password.pyis not. appsettings*.json,docker-compose.ymlandcompose.yml, lock files (package-lock.json,yarn.lock,pnpm-lock.yaml, anything ending in.lock), minified.min.jsand.min.css, and.mapfiles.- Anything inside these folders:
node_modules,dist,build,out,.git,__pycache__,.venv,venv,.env,.next,coverage,site-packages,.tox,env,.pytest_cache,eggs,.eggs,.ssh,.gnupg,.aws,.azure,.kube,.docker,secrets,.secrets,.nuxt,.terraform,dist-packages.
Folders are judged from inside your workspace folder, so a project that itself sits in a folder called build still indexes.
Limits
- Each file is cut at 50 KB.
- One run looks at up to 4,000 matching files and sends at most 500. When there are more, the choice is the same every time: a tenth of the places are kept for config files, source comes before config, and tests, snapshots and vendored files rank below the rest.
- The free plan keeps 200 files per project. Pro and Team have no file cap.
- The server takes 600 index requests per 15 minutes per account. Files go up 10 at a time, and a run stops after three batches in a row where every file was turned away. What it did not send is queued for the next run.
What leaves your machine
The text of each indexed file goes to DebugAI's servers over HTTPS, where it is split into chunks, embedded with Voyage AI and stored under your account for your own debugs. Other users cannot see it. Details in What leaves your machine.
Next
- Debug an error, now that DebugAI can read your project.
- Indexing went wrong: Indexing troubleshooting.