Troubleshooting

Wikilinks broken / backlinks missing

After rename / move the index occasionally lags; understanding the index model solves it for good.

Symptom

[[Some Note]] renders gray or red-squiggle ("unresolved") in the editor — even though you know Some Note.md is right there. Or the reverse: wikilinks render correctly but the right-side Backlinks panel is empty.

Both symptoms mean the link index has fallen behind the filesystem. Kition keeps wikilink relations under .kition/index/, and after renames / moves / bulk sync the index can lag from seconds to minutes.

Likely causes

A file was just renamed / moved by an external tool (Finder, git pull, rsync) and the fs watcher has not caught up
A cloud sync delivered the file behind Kition’s back, bypassing the filesystem listener
The link text’s case or whitespace does not match the filename (macOS HFS+ is case-insensitive, the index is not)
.kition/index/ is damaged or had a concurrent write conflict
[[#section]] anchor-only link with no target file

Step-by-step diagnostic

Bottom-right status bar — wait for "Indexing..." to clear
Hover the red link to see the expected path in the tooltip
In the vault, run ls "<expected path>" to confirm the file exists
Compare case exactly ([[Some Note]] vs Some note.md)
Palette → "Rebuild link index", wait 5-30s (depends on vault size)
If still broken, quit Kition, back up .kition/index/, delete it, relaunch — Kition will rebuild from scratch

Manual index check / repair

Close Kition first. If the command palette is unreachable, trigger a rebuild from the CLI:

# Rebuild the link index from disk
kition index rebuild

# Or verify only — reports inconsistencies without rewriting
kition index check

# Last-resort: wipe and rebuild from scratch
kition index reset --rebuild

Fix

Index lag: Palette → "Rebuild link index"
Case mismatch: rename the file or rename the link — pick one (kebab-case as a project rule works well)
DB damage: dump + reload as above, or delete the DB and let Kition rebuild
Cloud sync bypass: trigger a manual rebuild after every bulk pull
Anchor-only dead link: change [[#section]] to [[file#section]]

Workaround

While the index is rebuilding, full-text search (Cmd/Ctrl + Shift + F) still finds anything — it walks the filesystem, not the index. Use search as a stand-in for backlink navigation.

When to file a bug

After rebuild, many links remain "unresolved" while the files clearly exist
PRAGMA integrity_check errors repeatedly — suggests a bug in the write path
Renaming a single file does not auto-migrate backlinks (it should)
Index size is abnormal (> 30% of total Markdown bytes in the vault)

← Back to help center More in Troubleshooting →

Wikilinks and backlinks

`[[Doc name]]` creates a link; the backlinks panel shows what references the current page.