← back to Goodquestion Ai
src/content/posts/2026-02-21-the-animation-loop-that-wouldnt-animate.md
85 lines
---
title: '1 Boolean, 30,000 Lines, 3 Hours: The Stale Flag That Killed 60fps'
description: "A single forgotten variable froze my entire 3D app. Finding it took three hours. Preventing it takes one rule."
date: 2026-02-21
tags: ["debugging", "performance", "infrastructure"]
---
The screen was frozen. Not crashed -- frozen. Buttons worked. Menus opened. State updated in the background. But the 3D viewport was locked on a single frame, completely unresponsive. Camera controls, animations, transitions -- all dead.
The cause was one boolean variable, buried in 30,000 lines of code.
## The Symptom
The application runs a render loop -- a function that fires 60 times per second to draw the 3D scene. It had been working flawlessly for weeks. Then one morning, after merging a new feature, the viewport stopped updating.
The strange part: the first frame rendered perfectly. You could see the full scene, every object in place. But nothing moved after that. The render loop was running, but it was not rendering.
## Following the Trail
The render loop had a guard clause -- a simple check that pauses rendering when the user is in an overlay screen (like a meeting or a settings panel). The logic: if an overlay is active, skip the expensive rendering work and save processing power. Smart optimization.
I logged the guard variable. It was `true`. Always `true`. On every frame. The loop was firing 60 times per second, hitting the guard clause, and returning without ever drawing anything.
## The Three-Hour Search
The variable was declared with a default of `false`. Something was setting it to `true` and never resetting it. I searched the entire codebase and found three places that flipped it on:
1. When a camera animation starts (resets when animation ends)
2. When an overlay opens (resets when the user closes it)
3. During a window resize (resets after a short delay)
Each setter had a corresponding reset. Transition ends, overlay closes, resize settles. Except for one edge case.
The overlay code set the flag to `true` when it opened, and reset it to `false` when the user clicked the close button. Straightforward -- unless the overlay was triggered programmatically instead of by a user click.
That was exactly what happened. An automated system called the overlay function during startup. It set the flag to `true`. But since no visible overlay actually appeared, the user never clicked "close." The flag stayed `true` forever. The render loop ran 60 times per second, checked the flag, and returned empty-handed every single time.
## The Fix
Two changes. First, after the overlay loads its data, check whether it is actually visible. If not, release the lock immediately. Second, add a safety timeout: if the flag has been `true` for more than ten seconds, something went wrong -- release it and log a warning.
```javascript
// Safety timeout: never hold the render lock indefinitely
const safetyTimer = setTimeout(() => {
if (renderLocked) {
console.warn('Render lock held too long, releasing');
renderLocked = false;
}
}, 10000);
```
Ten lines of defensive code. That is all it took to prevent this class of bug from ever happening again.
## The Numbers
| Metric | Before fix | After fix |
|--------|-----------|-----------|
| Time to find the bug | 3 hours | -- |
| Lines causing the issue | 1 | -- |
| Frames rendered while bug active | 1 (first frame only) | 60 per second |
| Safety timeout added | No | Yes (10 second max) |
| Codebase size searched | 30,000 lines | -- |
## What This Means For Your Business
This bug pattern shows up everywhere, not just in 3D applications. Any time a system uses a flag to pause or gate a process, you are creating a contract: *something* will reset that flag. If the reset depends on a user action that might not happen, you have a time bomb.
Three rules that prevent this:
1. **Every lock needs a timeout.** If a flag blocks a critical process, it must have a maximum lifetime. If nothing clears it within a reasonable window, clear it automatically and log the anomaly.
2. **Audit every writer.** When a single variable controls critical behavior, find every place in the code that changes it. Not just the one you think matters -- all of them. The bug is almost always in the one you did not check.
3. **Log state changes during development.** A simple log message that fires every time a critical flag changes -- including where in the code the change originated -- would have caught this in seconds instead of hours.
The hardest bugs are rarely the complex ones. They are the simple ones hiding in plain sight, doing exactly what you told them to do.
## Let's Connect
- [Twitter/X: @AgentAbrams](https://x.com/AgentAbrams)
- [LinkedIn: Steve Abrams](https://linkedin.com/in/steveabrams)
- [YouTube: @AgentAbrams](https://youtube.com/@AgentAbrams)