Troubleshooting

The fixes for the things that break most often.

Monaco won't load

You open a file and see a plain <textarea>. Browser console says:

Loading the script 'https://cdn.jsdelivr.net/npm/monaco-editor@0.46.0/min/vs/loader.js'
violates the following Content Security Policy directive
[KFMonaco] load failed: monaco loader.js failed to fetch

Fix: Hard-refresh (Ctrl+Shift+R). The current build allows https://cdn.jsdelivr.net in CSP. The error is from a stale cached page or a stale Service Worker.

If hard-refresh doesn't fix it, also clear the Service Worker:

DevTools → Application → Service Workers → Unregister.

Terminal opens but nothing happens

You're probably on the legacy fake shell. Confirm:

KFTermPTY && KFTermPTY.flag

If it returns { on: false } or KFTermPTY is undefined:

localStorage.removeItem("kf.term.pty");
location.reload();

If KFTermPTY exists and on: true but the shell still isn't responsive, check the Network tab for failed /api/pty/* requests. A 401 means your session expired — sign in again.

"What's new" toast won't go away / won't show up

The dismissal is per browser, keyed kf.whats-new.tier3.seen. To re-show:

localStorage.removeItem("kf.whats-new.tier3.seen");
location.reload();

To never see it again, just dismiss it — the flag persists.

Browser tool always returns 403

Default-deny is doing its job. Open the allowlist (Ctrl+Shift+B), add the host you're trying to reach, save, retry.

If you've added it and still get 403:

  • Pattern mismatch — *.example.com does not match example.com itself. Add both.
  • Allowlist hit the 256-host cap — remove unused hosts.
  • Audit log will show the actual reason: audit browser.allowlist.deny url=https://... reason=....

Ask-the-codebase returns no results

The embed index either doesn't exist yet or doesn't include your file.

Check status:

curl -b cookies.txt /api/semantic/status

If exists: false, the index hasn't built yet. Save any file to trigger background indexing, or wait for the first-run pass to complete.

If exists: true but count is much lower than your file count, the indexer skipped large/binary files. That's expected.

Notebook cells run but produce no output

Two common causes:

  1. Subprocess mode doesn't preserve state across cells. If cell 1 sets x = 5 and cell 2 says print(x), you'll get NameError. Install jupyter_client to get kernel mode.
  2. Output is too long. The renderer caps display; the full output is in the saved .ipynb. Open the file and check.

My changes won't apply

The agent staged a diff but the Apply button is greyed out, or apply fails with "validation_hooks rejected".

  • The validation hook caught a syntax error or a forbidden pattern (e.g., a dropped import).
  • Click the failure reason for details.
  • Either edit the hunk manually before applying, or ask the agent: *"That patch failed validation because X. Try again."*

"Routes count" mismatch in CI

You see app-import: routes 437 instead of routes 436 (or whatever the brief says). You added a route. Update the brief's routes count and re-run CI.

Still stuck

  • Check the build brief for recent ticket annotations.
  • Open an issue with the contents of the browser console + the request that failed.