Fix: Unity Burst Compile Internal Error After Package Update

A DOTS-based game updates Entities. Reopening, Burst spits dozens of “Internal Compiler Error” messages. None of the jobs run. Editor falls back to managed code, performance tanks.

Clear Cache

Close Unity Editor.
rm -rf Library/BurstCache
Reopen Unity.

On first project load, Burst recompiles all methods. Slow first time (minutes); subsequent loads use the cache.

Force Recompile

Jobs menu → Burst → Recompile Library. Same effect, in-editor.

Package Version Alignment

Burst version must be compatible with:

• Mathematics (vector/matrix types).
• Collections (NativeArray, NativeList).
• Entities (if using DOTS ECS).
• Jobs.

Check Window → Package Manager. Versions advertised as “Verified for Unity X” usually align. Updating one without others is the most common breakage.

Check for Unsupported Constructs

Burst doesn’t support all C#:

• No managed types in jobs (string, class).
• No try/catch (in older Burst).
• No virtual calls except via function pointers.
• No exception throws — only safety checks in editor.

A new package version may tighten the rules. Read each error message; usually points at the unsupported line.

Inspect Burst Inspector

Jobs → Burst → Open Inspector. Pick a job; see the generated assembly and any compile warnings/errors. Quick way to confirm a specific job compiles cleanly.

Verifying

Run Play mode. Burst-compiled jobs run native (check Profiler → Hierarchy view; method names with [BurstCompile] tag should show no managed allocations). Performance back to expected.

“Cache and version mismatches cause most Burst headaches. Wipe and align is the standard recovery.”

For CI, delete Library/BurstCache before each build — ensures fresh compile and surfaces version issues at build time, not runtime.