Troubleshooting

Start with the last confirmed good state and the first concrete failure. Preserve your current work before trying broad recovery steps. Most problems become easier to diagnose when you distinguish source, generated assets, compiled output and saved app records.

1. Check the selected root and engine in the Recompile dropdown.

2. Confirm the intended source was saved and resolve any disk conflict.

3. Open the build log and start with its first error.

4. Inspect that source location and the lines immediately before it.

5. Fix the specific issue and compile again.

A displayed old PDF is not a successful build of new source. Check build time/status. If remote refresh or Figure Studio generation failed, resolve that earlier pipeline step before changing LaTeX unrelated to the failure.

Use Clean build files when stale auxiliary state is plausible after a structural change. Cleaning does not repair missing files, unbalanced braces or unsupported commands.

Compiler line numbers indicate where TeX noticed a problem, not always where it began. Inspect preceding groups and environments.

Check whether the app is using its packaged runtime or an external/local installation. Follow the offered package/runtime controls and read the exact missing dependency. Browser/source installations need their configured TeX environment available to the server process.

SVG conversion, bibliography backends, SSH data transfer and specialized builds may each have separate prerequisites. A package installed in a different shell environment may not be visible to the running app until configuration/restart is appropriate.

A dirty editor, external source change or newer domain-record revision can invalidate a preview. Keep your draft, inspect the current saved state, and refresh/rebase the proposed change. Copy important text before discarding any local draft.

Do not bypass the check by deleting .versofold files or blindly replacing the whole manuscript. Guarded workflows protect source, tables, board cards, research records and generated assets differently; follow the specific message.

Visual approximates supported template behavior. It does not run TeX float placement, line breaking or every custom macro. Check exact pagination and numbering in a fresh PDF. Use LaTeX source for unsupported structures.

An equation can fail the local preview while compiling correctly, or preview successfully while the document lacks a required package. The actual build resolves which behavior applies to the manuscript.

Check that the paper has an attached PDF and a usable text layer. Scanned pages need image inspection; OCR is not included. Try alternate terms, inspect the original page and read the coverage disclosure.

Registry metadata is not proof of claim support. An uncertain citation match needs a human choice. Missing search hits in a limited index do not prove no evidence exists.

Reopen evidence pages when an inspection record expires. Reattach manuscript anchors after wording changes or ambiguous duplicates. Recheck source fingerprints after replacing a PDF attachment.

For remote sources, verify SSH access, the host's Python prerequisite and whether the file changed during transfer. A complete old cache can be used only through the explicit stale fallback.

For Figure Studio, inspect recipe warnings, mappings, missing inputs and whether assets were published after the latest design change. Externally edited generated files require an explicit replacement decision. Frozen sources/assets remain pinned.

For linked results, refresh calculations and inspect row counts, filters and percentage formatting. Reconnect changed anchors. For tables, correct formulas before publication and remember that saving a draft does not republish output.

Check the current connection, model, mode, file scope and optional grants. A Discuss run cannot perform ordinary manuscript edits. A custom endpoint may not have verified tool support: its models can only discuss until you tick Tools verified on its card in Settings → Connections (only do this once you know the model handles tool calls). An external runtime may need login or a compatible installed version.

Read quota/authentication errors rather than repeatedly sending the same request. Review pending approval/question cards. Stop preserves completed changes; inspect activity before retrying an uncertain write.

Ask “Consult the handbook for this specific feature” when the obstacle is how to use VersoFold. If the problem is the manuscript's scientific content, the agent still needs to inspect that content.

VersoFold for Linux comes as a .deb for Ubuntu and Debian and as an AppImage for other distributions (x64).

• The AppImage does not start. AppImages need FUSE 2 (libfuse2 on Ubuntu, which recent releases no longer install by default). Install it, or run the AppImage with --appimage-extract-and-run. The .deb needs neither.

• Agent commands do not run. Commands and research scripts run in a bubblewrap sandbox (/usr/bin/bwrap). The .deb installs it; with the AppImage, install the bubblewrap package. Without it, a command reports that the Linux sandbox is unavailable instead of running unconfined.

• Keys are not remembered. Remembered keys are sealed by the desktop keyring (GNOME Keyring or KWallet, through libsecret). Without one, VersoFold asks for the key again in each session and never writes it to disk in the clear.

• Updates. An AppImage updates itself in place. A .deb install downloads the new package and opens it in the system's software installer, which asks for your password.

• Shortcuts. The app and this handbook show Ctrl and Alt where a Mac shows ⌘ and ⌥.

Use editor Undo for immediate mistakes, Review changes for a current diff, and Versions for older source. Preserve hidden history in backups; lost Git objects cannot be recreated by the app.

Use Help → Report a bug with the action, expected result, actual result and relevant error. Settings/Home also expose feature requests. Include only material you intend to share; project prose and credentials are not automatically necessary to explain a UI error.