The Stale Godot Class Cache Bug That Passed CI but Broke Local Startup
A developer shares how a tricky stale class cache bug in Godot 4 slipped past CI checks but triggered parse errors during local startup.
Stock photo for illustration only, not from the actual event
- Nocturne Vania, a pixel-art Metroidvania in Godot 4, hit a subtle cache bug.
- CI passed because it fresh-imported, but stale local caches caused parse errors.
- Fixed by switching from global names to direct script paths and preloads.
- Added a static check script in PR #95 to prevent future regression.
Building games with modern engines like Godot 4 often relies heavily on the class_name keyword for convenient global type references. However, the solo developer behind the pixel-art Metroidvania project Nocturne Vania encountered a frustrating hurdle after expanding the game world with a new bell tower area containing fresh rooms, enemies, visual effects, and map markers.
The peculiar nature of the bug meant it worked seamlessly in a freshly imported project environment and passed all automated Continuous Integration (CI) checks without a hitch. Yet, launching the game on an existing local checkout frequently resulted in a parse error. Godot stores imported project data inside a .godot directory, meaning an editor session predating the new scripts still held onto a stale global_script_class_cache.cfg file.
Relying on engine-generated cache files often introduces hidden discrepancies between developer workstations and automated testing pipelines. Since CI environments typically perform clean checkouts and fresh imports, they mask initialization issues that occur when local checkouts inherit outdated state files. Eliminating reliance on global name resolution for critical boot paths is a robust engineering practice to prevent environment-specific fragility.
To establish a durable fix that does not rely on a freshly generated editor cache to parse correctly, the developer restructured references across 19 files, resulting in 81 additions and 33 deletions in PR #95. Room scripts were updated to inherit directly from script paths rather than global names, and runtime checks were rewritten to explicitly preload script resources instead of forcing the parser to resolve global identifiers.
Stock photo for illustration only, not from the actual event
Furthermore, a targeted static analysis check was integrated into the workflow to catch cache-sensitive global name usages outside their designated declarations. This ensures that any direct references to newly introduced global classes are flagged immediately during code reviews or automated checks.
Following these architectural adjustments, the complete test suite successfully passed across all categories, alongside validation checks for 911 media assets, permanently resolving the fragile startup dependency.
Source: Dev.to
Found something wrong in this article? Report an issue with this article
Comments
Leave a Comment