Three OpenSCAD Problems and How to Solve Them

1. The Preview-Is-Smooth, Render-Is-A-Garbage-Fire Problem

You've modeled a bracket with a hundred for() loops and a few minkowski() fillets. Preview (F5) runs in 0.3 seconds, but F6 (full render) locks up your machine for four minutes, then spits out a 3 GB STL that takes half an hour to slice. I've seen this on i7s, Xeons, and even a Threadripper the pattern is the same. The problem isn't your CPU; it's how OpenSCAD handles CSG (Constructive Solid Geometry) under load.

OpenSCAD's preview uses a lightweight triangulation, basically a sketch. Render forces full boolean CSG operations union, difference, intersection on every primitive. If you've nested operations, especially with minkowski() or hull(), the solver goes recursive thrash.

My Field Workflow

• Step 1: Set $preview = true/false at the top of every module that uses minkowski() or hull(). In preview, replace them with a chamfered cube equivalent saves 90% of render time.
• Step 2: Never put minkowski() inside a for() loop. Do the fillet on a single union, then rotate the result. I learned this after a 24-hour render that crashed on a power flicker.
• Step 3: Use render() sparingly. If you render() a complex difference, you force CGAL to compute it every time. Instead, export the intermediate part as a separate STL and import it.

Pro tip from a buddy who runs a print farm: If you have repeating patterns, generate the pattern in Python or a shell script, output a list of includes, and compile them with use instead of include. The use directive only compiles the module once, while include re-evaluates the whole file. I've cut render times from 45 minutes to 4 by that alone.

2. The "WTF, Undefined Variable!" Error Spiral

OpenSCAD's functional language is a blessing and a curse. You write a nice module, pass a parameter, but somewhere inside a nested for() you call a variable that 'should' exist except OpenSCAD's scoping rules treat every for() loop as a new scope for let() assignments. I've spent an hour chasing a bug where a child module couldn't see a parent's variable because it was assigned inside a for() iterator.

Example: you write for (i = [0:5]) { and inside you try to use i again in a children() call. It works on the first iteration, fails on the second because i is re-scoped in the child call. The error message is usually "WARNING: Ignoring unknown variable 'i'" but you literally just defined it.

Root Cause (from the Trenches)

OpenSCAD doesn't have mutable variables. Every let() creates a new binding. If you pass a variable into a module, it's passed by value, not reference. Inside the module, if you try to modify it (e.g., i = i + 1), you're actually creating a new local variable, but the loop iterator stays unchanged. The debug output shows "ECHO: i = 5" because it's printing the local version, not the loop's version.

My go-to solution: I now treat every variable as if it lives only in the function scope it's assigned in. If I need to use a loop variable inside a nested call, I explicitly pass it as a parameter. It's verbose, but it's saved me from three-hour debugging sessions. Also, never rely on global variables inside modules I always pass them in. That way, if you rename the global, you get a compile-time error, not a runtime warning.

Step-by-Step Debug Workflow

1. Add echo("myVar=", myVar); at every step inside the module, inside the loop, inside the child.
2. Check if myVar appears in the console as undefined despite being defined before the module call.
3. If you find it's undefined inside a for() loop that you passed to a child, fix by passing the value: childModule(loopVar = i);.
4. If you're using children() and need the loop index, pass it as a $var (special variable) those are injected into all children automatically. Example: $i = i; before children().

I've had sessions where I thought OpenSCAD was broken, only to find I'd accidentally used a variable name that was also a reserved word. dot and cross are safe; min and max are functions, not variable names, but you can still shadow them. Just don't.

3. STL Export: The Non-Manifold Geometry Nightmare

You've spent hours getting the perfect parametric shape. F6 renders without error. You export to STL, open it in a slicer, and the slicer throws "non-manifold edges" or "hole in mesh" or "model is not watertight". The slicer shows you a red blob with missing faces. I've seen this with thin walls, overlapping unions, and especially when using difference() with a translate() that leaves zero-thickness walls.

The physics: OpenSCAD's CSG operations produce boundaries that are theoretically perfect, but when triangulated, numerical precision issues create gaps. If two surfaces are exactly coplanar, the Boolean engine sometimes leaves a sliver of space a non-manifold edge. The slicer can't tell which side is interior vs exterior.

My Diagnostic Checklist

• Check for zero-thickness walls: Use intersection_for() or minkowski() with a tiny negative offset. If your wall is, say, 0.2 mm, but your printer's nozzle can't do that, OpenSCAD's render still creates it but the STL will have overlapping triangles.
• Use the "Layer View" in slicer: If you see a missing layer line, that's a non-manifold edge. In PrusaSlicer, the "Fix through NetFabb" option often works, but it can change dimensions. I'd rather fix at source.
• Run polyhedron() checks: If you're building with polyhedron, ensure all faces are wound counterclockwise as seen from outside. One flipped face breaks the mesh.

The Nuclear Option: Mesh Repair Tools

Sometimes you just can't fix it in OpenSCAD quickly. I keep a copy of NetFabb Basic (or the command-line admesh) on my workstation. Run admesh --disable-banner --write-ascii --normalize model.stl fixed.stl. It automatically stitches non-manifold edges by moving vertices within tolerance. But be warned: admesh can shrink or enlarge parts by up to 0.005 mm. For precision parts, that's a fail. I only use it for rapid prototyping, never for fixtures.

Another trick: Export as OFF format, then use Meshlab to close holes with "Close Holes" filter. But that's a hack. My preference is to never export a broken STL. That means being paranoid about zero-thickness features. I add assert(min_wall > 0.4); at the top of my modules to catch design errors before render.

Final note: If you're using OpenSCAD 2021.01 or later, the exact_bolts library from the community has a function clear_clearance() that automatically offsets difference operations. I've started wrapping every difference() in that function it adds 0.1 mm to the cutting object. Saves me headaches.

That's the big three. I've got a dozen more smaller ones (the surface() function eating huge PNGs, the import_dxf being janky with arcs, the lack of a measure tool), but those three are the ones that every user hits eventually. Mind the scoping, be aggressive with render optimization, and always give your cuts a hair of tolerance. Your slicer will thank you.