Troubleshooting

Things go wrong sometimes. Here's how to fix the common stuff.

Compilation engines

Flow supports two categories of LaTeX compilers:

• Tectonic (bundled) — Ships with Flow. No installation needed. Handles package downloads automatically. This is the default and recommended for most users.
• System compilers — If you have TeX Live installed, Flow can also use pdfLaTeX, XeLaTeX, or LuaLaTeX. These appear in Settings > Compiler when Flow detects them on your system.

You can switch engines in Settings > Compiler. If one engine gives you trouble with a particular document, try another.

Common LaTeX errors

Undefined control sequence

You used a command that LaTeX doesn't recognize. Usually this means a missing \usepackage declaration. For example, \textcolor requires \usepackage{xcolor}.

With Tectonic, missing packages are downloaded automatically. With system compilers, you may need to install them via tlmgr install <package>.

Missing $ inserted

You have a math character (like _ or ^) outside of math mode. Wrap it in dollar signs: $x_2$ instead of x_2.

File not found

An \includegraphics or \input command references a file that can't be located. Check that:

• The filename and extension are correct (LaTeX is case-sensitive on Linux).
• The file is in your project folder or a subfolder. Flow adds your project directory and all its subdirectories to the search path, so you can reference files by name without the full path.

Overfull/Underfull hbox

These are warnings, not errors — your document will still compile. They mean LaTeX is struggling to lay out a line neatly, usually because of a long word or URL. You can often fix these by adding \sloppy or using the microtype package.

Environment already defined / Command already defined

Two packages are defining the same thing. Try changing the order of your \usepackage declarations, or use \renewcommand instead of \newcommand.

Missing packages

Tectonic handles package management automatically — when it encounters a missing package during compilation, it downloads it from its own bundle. You generally don't need to do anything.

System TeX Live requires manual package management. If you see "File not found" errors for style files (.sty):

# Find which package provides a file
tlmgr search --global --file "missing-file.sty"

# Install it
sudo tlmgr install package-name

AI error explanations

If you have an LLM provider configured, each compilation error gets an "Ask AI" button. Click it to get a plain-English explanation of the error and a suggested fix.

You can also enable Auto Ask AI in Settings > AI Apprentice to have this happen automatically for every error. This is particularly helpful if you're new to LaTeX.

Auto-update issues

Flow checks for updates automatically — first at 10 seconds after startup, then every 4 hours. Updates are downloaded in the background and installed when you quit the app.

If an update download fails (network issues, etc.), Flow will try again at the next check interval. It won't interrupt your work.

Performance tips

• Large documents — If the editor feels slow on very large files, try disabling freeform ghost suggestions, which reduce the background processing load.
• Local LLMs — If ghost suggestions are slow, check your GPU status in Settings > LLM Providers. GPU acceleration (Metal, CUDA, or Vulkan) makes a big difference. You can also try a smaller model.
• Compilation speed — Tectonic's first compile of a new template may take longer as it downloads packages. Subsequent compiles use the cached packages and are much faster.