Documentation
Troubleshooting
First steps
- Look at the Log tab in the bottom dock, and at the red error text in the parameter panel of the failing node.
- Open the engine log: %APPDATA%\Tessera\engine.log. The last lines usually name the problem.
- Close Tessera completely and start it again. This restarts the engine and clears every in-memory cache.
%APPDATA%\TesseraInstalling
- “Windows protected your PC”
- The installer is not code-signed yet. Click More info > Run anyway, only for files from this site or GitHub releases.
- Antivirus quarantines a file
- The installer bundles a Python runtime with compiled libraries, which some scanners flag heuristically. Restore the file or add an exception for %LOCALAPPDATA%\Programs\tessera, then reinstall.
Engine and window
- The engine dot is red or the viewport stays empty
- Restart Tessera. If it keeps failing, check %APPDATA%\Tessera\engine.log. Tessera uses port 7419 and moves to the next free port if another program holds it. If an engine started by Claude Code (MCP) is running, the app reuses it; if that engine is from an older version, end the
python.exerunningtessera.serverin Task Manager and restart. - The window is blank or the viewport is black
- The viewport needs WebGL2. Update your graphics driver. On laptops with two GPUs, set Tessera to use the high-performance GPU in Settings > System > Display > Graphics.
- My last session didn’t reopen
- Open tabs come from %USERPROFILE%\Tessera\session.json and the autosaves in %USERPROFILE%\Tessera\projects. Saved scenes are in %USERPROFILE%\Tessera\scenes; open them with Open.
AI
- Provider not found
- Claude needs the Claude Code CLI (
claude) installed and signed in; GPT needs the Codex app signed in with ChatGPT; Tessera AI needs Ollama with a model. Restart Tessera after installing. Hover the provider menu to see what was detected. - Usage limit or credits reached
- Claude and GPT run under your own plan; the provider’s message appears in the AI log. Wait for the reset, switch provider, or use Tessera AI offline. What was built so far stays in the graph.
- “no local model installed”
- Pull one:
ollama pull qwen3-coder:30b, orollama pull qwen3.5:9bfor smaller GPUs. - Local AI is slow
- The model doesn’t fit in free VRAM (often because Unreal or a game is using the GPU) and runs partly on the CPU. Close GPU-heavy apps, use a smaller model, or leave the model on auto so Tessera picks one that fits.
- The AI builds the wrong thing
- Be specific: name each part, give sizes in metres and positions. Correct it in the same chat (“the roof is floating, fix it”), or press New chat to start over. Undo steps back through its edits. See Writing good prompts.
Unreal
- “No Unreal editor found”
- Enable the Python Editor Script Plugin and Project Settings > Plugins > Python > Enable Remote Execution, restart Unreal, keep the project open, then Refresh in Tessera’s Unreal panel. Allow Unreal through the firewall if asked.
- “The linked project is not open”
- The link is pinned to the project you first used. Open it, or pick the current editor in the Unreal panel to re-bind.
- The mesh in Unreal is grey
- The geometry has no
Cdcolours. Add acolorormaterialnode before sending.
More in Unreal live link.
Cooking and performance
- A node shows an error
- Read the message in its parameter panel: most are a missing input, a parameter out of range or an expression typo (the message names the node and parameter). Fix it or bypass the node with B.
- “unknown parameter” from a script
- Parameter names must match exactly; see the node reference or
/api/types. - Everything is slow
- Heavy nodes are erosion at high resolution, sculpting and
sculpt_detail, big villages withsculptedon, and simulations. Lower resolutions while you work, bypass heavy nodes, display a lighter upstream node, and shorten the frame range. - Running out of memory
- Simulation caches keep every frame in memory. Reset the sim, reduce its resolution or frame range, and close project tabs you don’t need. 16 GB RAM is recommended.
- The first cook of a node takes long
- Accelerated nodes compile their code the first time they run. Later cooks are fast.
Safe reset
If Tessera misbehaves right after start (for example a project that crashes the engine on load), reset the session without losing files:
- Close Tessera.
- Rename %USERPROFILE%\Tessera\session.json to
session.old.json. - Start Tessera: it opens a fresh, empty session. Your saved scenes and the project autosaves in %USERPROFILE%\Tessera\projects are untouched; open them again one by one with Open to find the problem.
For a complete reset, uninstall, then delete %USERPROFILE%\Tessera and %APPDATA%\Tessera (back up anything you want to keep first).
Reporting a bug
Open an issue on GitHub with your Tessera version, engine.log, the steps to reproduce and, if possible, the scene .tsr. See how to report a bug.