Docs · chapter 8

Troubleshooting

Updated 14 November 2026 · version 0.17

What goes wrong most often, and what to do. The last lines a recording prints always say how the program ended: start there.

Windows Defender

Windows Defender can silently block the launch or slow the trace down.

The launcher can be quarantined or killed with no message, and a run can be several times slower while real-time scanning inspects the traced process.
Recommended: add the folder that holds ProtoTTD.exe and the traces, and the target program's folder, to the Microsoft Defender exclusions (Windows Security > Virus & threat protection > Manage settings > Exclusions).
If the launcher seems to do nothing, look in Protection history first.

What you see	What to do
Nothing happens when you press Record, or the program is gone at once	Look in Defender's Protection history (above), then at the window's last message: a program that needs another folder to start in takes it in the Record tab.
The run is very slow	Exclude the folders from Defender. Then record less: `"trace_from"` to start later, a thread rule to leave noisy threads out, `"exclude_modules"` for a library that is only noise.
The disk fills up	A busy program writes gigabytes a minute. Move the runs folder to a big disk (Record tab, Change…), and stop sooner with `"stop_after"`.
The program behaves differently while recorded	It may measure time or look for a debugger. The template Hide the tracer's slowness fixes the clock and CPUID; a patch rule can answer any other check.
It never exits	Ctrl+C (or Stop) ends it and keeps the trace; a second one kills it. `"stop_after"` does it by itself.
[trace-from] … was never reached	The trigger did not happen in that run, so nothing was recorded. Check the module and function name, or count (#N) lower.
The program crashed	The last lines name the exception and where it happened. The capture is kept and opens: go to its end to see the crash.

What you see	What to do
No source lines or variables	The PDB is not found: put it beside the program, or name it for the module (`.reload app=C:\build\app.pdb`). Sources moved since the build: `.srcpath <folder>`.
Windows' functions have no names	`.sympath srv*` downloads Windows' symbols from Microsoft's server.
A value shows as unknown	The run never showed it before this instant: memory not yet touched, a register after a call into a library left out of the trace. Go forward to where the program uses it.
The first opening of a big capture takes a while	The window counts the run once and writes an index into the capture; every later opening takes about a second.

What you see	What to do
The agent connects but does nothing	An MCP server cannot start anything: ask it something, with the word protovision.
It does not see the window	Is the window signed in, and Let agents work in this window on? The pane's top line says whether an agent can work there.
It does not see a served trace	The terminal that serves it must stay open, with PROTOVISION_TOKEN set when it started.
Errors right after an update of the site	Reconnect the MCP server in your client (in Claude Code: /mcp), open the project again, go on: the session is kept.
The structure is locked	Function-level answers need PROTOVISION_TOKEN on the program that serves the bundle. Instruction-level tools work meanwhile.
Out of credits	Your account page shows the balance and sells more. Everything you do yourself stays free.

Limit	Value
Free use on your machine	3,600 debugger commands and 600 analysis calls an hour
An agent's call	0.25 credit; 200 credits on a new account; the docs tool is free
Windows	64-bit Windows; 64 and 32-bit programs
A trigger's N-th time, a stop_after	#N any count; stop_after from 1 to 86400 seconds
Rules	4096 code rules and 256 thread rules; 64 steps and 256 bytes per rule

Something else? Write to contact@protovisionrun.dev with the last lines the recording printed.