Docs Reference
Troubleshooting
Symptoms, likely causes, and what to try. Where a fix is a setting, the setting name links back to Settings & Commands.
Setup#
The Blacksite icon isn’t in the activity bar#
The extension didn’t activate. Reload the window (Developer: Reload Window). If it still isn’t there, check Extensions for Blacksite and confirm it is enabled and not showing an error.
Blacksite requires VS Code 1.139 or newer — check Help → About. An older VS Code refuses to install the VSIX, and the built-in updater tells you which VS Code version a release needs instead of offering it. Forks built on an older VS Code base (Cursor was on 1.105 in mid-2026) cannot install Blacksite 1.30 or later.
“No API key configured”#
Run Blacksite: Set API Key and pick the provider selected in the sidebar Settings. Keys are stored per provider, so a key saved for Anthropic does nothing while the provider is set to OpenAI.
Bedrock authentication fails#
Blacksite uses the standard AWS credential chain. Test it independently:
aws sts get-caller-identity
If that fails, Blacksite will too. If it succeeds but Blacksite doesn’t, check that the profile you’re relying on is the default one — Blacksite reads the chain, not a Blacksite-specific profile setting.
A model I expect isn’t in the list#
Two common causes:
- Bedrock, newest Claude models — switch the Bedrock API to
mantlein the sidebar Settings. The Converse API doesn’t carry the newest models; the Anthropic-native Messages endpoint does. - Account access — model availability is per account and per region. Check your provider console.
You can always set a model directly with /model <name>, which bypasses the picker entirely.
The agent#
It stopped mid-task#
Check for an unanswered prompt first — a modal approval or a question card blocks the loop until you respond. The transcript will show where it stopped.
If it genuinely ended early, /retry resends your last message. If it ends early repeatedly on the
same request, the request is probably too large for one turn; break it into steps, or switch to the
Plan profile and get a plan first.
It edited the wrong thing#
Diffs are approved before they land, so the change is reviewable — but if one slipped through, git diff and revert.
The usual root cause is ambiguous scope. “Fix the login bug” gives the agent a search problem;
“the session token isn’t refreshed in src/auth/session.ts — trace why” gives it a location. Use
@ mentions and Attach File To Chat rather than describing files in prose.
It’s using stale knowledge of a file#
Blacksite tells the agent when it’s editing from a stale copy, but you can force the issue: mention the file explicitly, or ask it to re-read before changing. If the index is stale rather than the file read, run Blacksite: Rebuild Codebase Map Index.
It keeps asking for approvals#
Working as designed. If a specific binary is safe in your project, choose “always allow” once — it
persists to blacksite.permissions.autoApprove.
Before you add anything broad, read
Approvals & Safety: auto-approving git also
auto-approves git push --force.
It refuses to run a command#
Check blacksite.permissions.deniedCommands — deny overrides everything else.
If the command carries an inline-eval flag (node -e, python -c), it’s blocked by default; see
the eval-flag exception before enabling it.
If the binary simply isn’t in the built-in allowlist, add it to
blacksite.permissions.allowedCommands.
Web research is denied and no approval card appears#
A request denied in a fraction of a second means no one was asked: a rule answered for you. The
reason is in the tool result and in the execution log. Either a domain you denied matches, or
Unknown domains in Browser & Research is set to Deny (blacksite.research.unknownDomainPolicy),
which refuses every site not already approved. The panel also shows a notice when a saved value could
not be used (a hostname that is not valid, a search provider this version does not know) or when the
whole policy could not be loaded; in that case research stays off until it can be. Reload the window if
Blacksite was just updated (see below), then confirm the policy in the panel.
Responses are getting slow or expensive#
Long conversations carry a large prefix. Two things help:
/compact— summarize older history and reclaim context. Costs one model call, buys back room./clear— start fresh when the new task genuinely doesn’t need the old context.
The Inspector (ⓘ in the chat header) shows how full the window is and what the last turn cost. Note that a long conversation is usually cheaper than its token count suggests, because most of the prefix is a cache hit — a fresh conversation re-pays for the whole prefix.
The context window keeps overflowing#
Reduce what’s riding along:
- Disable Base Context topics that aren’t relevant to the current work.
- Prefer attachments over pasting file contents — attachments are retrieved on demand.
- Disable tool families you don’t use; the catalog itself takes space.
Codebase Map#
The map is empty or missing files#
The index may still be building — it runs in the background on first open. Give it a moment on a large repository.
If it’s finished and files are still missing, you’re likely hitting a cap. Raise
blacksite.graph.performanceProfile from balanced to large or extreme, or set
blacksite.graph.maxIndexedFiles explicitly.
Force a rebuild with Blacksite: Rebuild Codebase Map Index.
The map is slow#
Lower blacksite.graph.performanceProfile to safe, or cap
blacksite.graph.maxRenderedStars directly.
Above 6,000 nodes Blacksite switches from force-directed layout to a linear-time packing, so very
large graphs stay responsive — but rendering tens of thousands of stars is still work. Turn off
blacksite.graph.backgroundSymbols if it’s on; it’s the most expensive layer.
Relationships I know exist aren’t drawn#
Service edges require the client side of a call to be verified before an edge is drawn. That’s deliberate — it means a line is a call that plausibly exists rather than two strings that rhyme, at the cost of missing some real relationships.
For a relationship that matters and can’t be detected, attach a relation note. Notes are
first-class graph edges: they render on the map and are traversable by map_impact and map_path.
map_relationships returns no symbol relations#
blacksite.graph.backgroundSymbols is off (the default). The result carries
symbolRelationsUnavailable: true in that case, so “not analyzed” is distinguishable from “none”.
Turn it on if you want symbol-level precision and can afford the indexing cost.
Data workbench#
“Database engine unavailable”#
A SQLite binding isn’t present. The rest of Blacksite works normally — chat, map, plans, and context don’t depend on the database. The Data view reconnects once a binding is available.
The agent references tables that don’t exist#
Its catalog is stale. Run Blacksite: Refresh Data Catalog.
A query returns fewer rows than expected#
Read queries are capped by blacksite.data.maxQueryRows (default 500), and previews by
blacksite.data.previewPageSize (default 50). Raise either, or narrow the query.
The agent won’t run a write#
By design. The agent classifies write and DDL statements without executing them and hands the result to you. Run it yourself in the Query tab.
Language intelligence#
Code intelligence tools return nothing#
They query your installed language servers. If VS Code itself can’t do Go to Definition in that file, neither can Blacksite.
Check that the language extension is installed and has finished initializing — most language servers
need a moment after a window opens, and some need a project file (tsconfig.json, go.mod) to
activate at all.
Rename didn’t catch everything#
code_rename uses the language server’s own rename refactor — it’s the same operation as VS Code’s
F2, with the same coverage. Anything it missed, the editor would have missed too. Dynamic
references (string-keyed lookups, reflection) are the usual culprits, and text search is the fallback
for those.
Updates#
Update check fails#
Blacksite updates from its own published releases, not the Marketplace. Failures are usually network or proxy related — no credentials are involved, so a failure is never an auth problem and there is no token to configure.
The updater reads the static latest.json published with the site first, and only falls back to
api.github.com if that is unreachable. The API allows 60 unauthenticated requests per hour per IP,
which several developers behind one corporate NAT will exhaust — a 403 or 429 from GitHub means
that limit, not a permissions problem, and it resolves on its own.
If your proxy blocks the site, point blacksite.updates.manifestUrl somewhere reachable that serves
the same manifest, or rely on the GitHub fallback via blacksite.updates.repository.
Turn the check off with blacksite.updates.checkOnStartup: false and install VSIXs manually if your
network makes it unreliable.
I want prerelease builds#
Set blacksite.updates.includePrerelease: true in your user settings. A workspace’s
.vscode/settings.json cannot choose where updates come from, so the setting is ignored there.
Blacksite updated but still behaves like the old version#
An update installs into VS Code but does not run until the window reloads. After a self-update, Blacksite keeps Reload to finish updating Blacksite in the status bar until you do. A window left open for days keeps running the previous build, including its tool descriptions and its research policy, so a setting written by the new build can be rejected by the old one. Run Developer: Reload Window.
A release was published but I was not offered it#
Open the Blacksite Updates output channel. Each check records its channel, what it found, and why it did or did not offer an update: a failed request, a version you dismissed (run Blacksite: Check for Updates to see it again), or a release that needs a newer VS Code than the one running. VS Code installs its own updates on restart, so a window left open for days keeps running the old version.
Getting more detail#
Blacksite: Show Execution Logs opens the execution log for this workspace: every tool call, its input, its result, and its timing. When something went wrong several steps back, this is far more informative than reconstructing it from the transcript.
For extension-level errors, Developer: Toggle Developer Tools shows the webview console, and the Output panel has a Blacksite channel.
If something looks like a genuine bug, the source is public — open an issue with the relevant execution log excerpt.