Troubleshooting

Troubleshooting

folea opens the start screen

folea reopens only a last-vault path that is still absolute, accessible, and a directory. If validation fails, it removes that path from saved state and shows the start screen.

Choose Open vault again. If the vault is still in Recent vaults, you can also select it there.

Closing a vault does not clear it as the last vault. Removing that same row from recents does.

A note is missing from the tree

Check these rules:

• The filename must end exactly in .typ.
• The note must not be inside .obsidian, .git, node_modules, .folea, .folea-cache, or _templates.
• The tree hides any path with a segment beginning with ..
• Tree filtering with / searches note title and relative path, not note contents.

Dot-prefixed notes can be in the index while remaining hidden in the tree. This can make the tree's header count larger than its visible row count.

Vault search misses a note

Vault search asks ripgrep for *.typ, but it also:

• excludes _templates/**, node_modules/**, .folea/**, and .folea-cache/**
• normally skips hidden paths
• respects ignore files such as .gitignore
• stops at 500 hits or 256 KiB of preview text

Only vault search reports truncated. Current-note search silently stops at 500 hits.

Quick-open content search uses the same vault search service, but quick open does not show search errors. It may stop and show No results.

Search opens the right note but not the right place

This is expected for quick open. Ctrl+p shows recent notes first, then searches note contents after you type. Choosing a search result opens the note but does not jump to the matched line.

Use / for the current note or Open vault search (search.openGlobal) for a result that reveals the matching rendered span.

The displayed vault-search column is based on ripgrep's UTF-8 byte offset. With non-ASCII text, it may not match a character count.

Search case or highlighting looks inconsistent

search.inFileCaseSensitive controls source hit collection. Rendered highlighting and n / N navigation currently lowercase both the query and rendered text. A case-sensitive source search can therefore still navigate through case-insensitive rendered spans.

The highlight covers the rendered text span containing a match, not always the exact substring.

A note does not update after saving

Normal .typ files are watched. Files inside ignored directories are not, including _templates and .obsidian.

If you changed a template, Typst package cache file, or another file under an ignored directory, close and reopen the vault. There is no user-facing refresh command.

For normal note files, folea waits for a stable write and coalesces delete-and-recreate save patterns. A brief delay is expected.

A compile error is missing or the old page stays visible

Behavior depends on when compilation failed:

• Opening or navigating to a broken note replaces the document with Typst compile error and diagnostic severity, location, and message.
• A worker failure is shown as Typst worker error: ....
• A failed save-triggered rerender keeps the previous good rendering visible and currently suppresses the new diagnostic.
• If source reading fails after a persistent rendering was already painted, that cached rendering stays visible. Without a cache hit, folea shows Unable to read selected note.

Open the source in your editor and compile it there if you need a diagnostic after a failed live rerender.

An import or package is missing

folea supplies normal vault .typ files, _templates .typ files, and this compatibility package-cache path to Typst:

<vault>/.obsidian/plugins/typst-for-obsidian/packages

That package path may contain .typ files and typst.toml. folea does not download or install packages. Package imports beginning with @ are not entries in folea's note-link graph.

Check that the required files already exist and that the render snapshot remains under 10,000 text files and 50 MiB. Reopen the vault after changing _templates or .obsidian files.

A link is missing from backlinks or does not open

The graph recognizes literal double-quoted source forms only:

#link("note.typ")
#import "shared.typ"
#include "section.typ"

It does not index wiki links, variables, labels, escaped-quote targets, package imports, or references inside comments and strings.

Targets must resolve to a known note without escaping the vault. .typ can be inferred only when that note exists. Query and fragment suffixes are ignored while locating the note.

Rendered http:// and https:// links open externally. Other schemes such as mailto: are treated as note targets and normally remain unresolved. An unresolved rendered note link produces a console warning rather than a notification.

The external editor does not open

1. Confirm that editor.command contains an executable.
2. Put %FILE% in the command as a complete argument.
3. Remember that no shell runs: pipes, $VARIABLES, command substitution, and globbing are not expanded.
4. Restart or reopen the vault after general preference edits. editor.command itself is read again for each editor open.
5. Check the terminal or application console for:

[folea] editor launch failed: ...

With no command, folea tries:

code --reuse-window <absolute-note-path>

On Linux and macOS, an existing vault-specific Neovim socket is tried before the configured command. A stale socket is removed after a failed remote attempt. macOS asks the login shell for PATH before spawning the editor.

See Configuration: external editor for examples.

Configuration changes do not apply

There are no config watchers.

• Restart after editing keys.config.
• Restart, or close and reopen the vault, after manually changing search or theme preferences.
• editor.command is read again for the next editor open.
• Theme palette commands apply immediately.
• theme = system follows OS theme changes immediately.

Only the first config warning is shown in the status line. Inspect the file for unknown keys, invalid booleans/themes, invalid chord syntax, or binding conflicts.

See Configuration.

The tree stays active after opening a filtered result

Current tree-search behavior leaves the tree context active after Enter opens the selected note. Press Escape to close the remaining tree.

A rendering looks stale

First reopen the vault, especially if the changed input is under _templates or .obsidian.

Then try : → Clear current vault cache. This removes only:

<vault>/.folea/render-cache/

It keeps vault preferences and reading state.

Clear application cache clears Electron web and code caches. It does not clear vault render caches, preferences, or reading state.

See Caching and State.

Saved state is corrupt

folea automatically starts fresh and tries to rename an invalid whole state file:

<userData>/state.json.corrupt-<timestamp>
<vault>/.folea/state.json.corrupt-<timestamp>

Invalid individual recent-note or note-position entries in vault state are skipped instead of resetting the entire file.

Do not delete prefs.config or keys.config unless you also want to remove those settings.

Report the exact build

When your installation provides the folea command, run:

folea --build-info

Source installs do not provide that command on every platform. Include the operating system, package format, and build information when reporting a problem.