Three OpenSCAD Problems and How to Solve Them

The Industrial Maker is reader-supported. When you purchase equipment, parts, or materials through links on our site, we may earn an affiliate commission at no additional cost to you.
OpenSCAD: Three Real-World Headaches (and How I Beat Them on the Shop Floor)
After 20 years of parametric design busting my knuckles, I've seen OpenSCAD choke, stall, and vomit geometry more times than I can count. This isn't a beginner tutorial it's a field log of the three issues that actually waste your time, and the exact workflows I use to keep the bits spinning.
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.
Workshop Alert: The Real Culprit
Nine times out of ten, it's $fn set globally to something silly like 100. That gives you a million triangles on a simple cylinder. For preview, you don't need that. I set $fn = 50 for preview, then bump to 100 only at final render and even then only for visible surfaces. Use $fa and $fs to control facet angle and size; they scale better.
My Field Workflow
- Step 1: Set
$preview = true/falseat the top of every module that usesminkowski()orhull(). In preview, replace them with a chamfered cube equivalent saves 90% of render time. - Step 2: Never put
minkowski()inside afor()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 yourender()a complex difference, you force CGAL to compute it every time. Instead, export the intermediate part as a separate STL and import it.
Physics of Failure
The default CGAL (Computational Geometry Algorithms Library) settings use a naive Boolean kernel that doesn't cache intermediate results. Each difference() step re-evaluates all children. With 50 iterations, that's 50 full CSG evaluations. On a part with 10k triangles, that's half a million operations and each operation checks every triangle intersection.
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.
Diagnostic Grid
- Error message: WARNING: Ignoring unknown variable 'j' or 'i' in module 'myModule'
- Common scenario: Using a loop counter inside a
children()call - Field fix: Pass the counter as a named argument to the child module, e.g.,
myModule(iter = i);then accessiterinside. - Better fix: Write pure functions without state. Use
list comprehensionandconcat()to build arrays, then collapse them withunion().
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.
Pro Tip: The "Ghost Variable" Trap
Sometimes OpenSCAD's $children variable is the culprit. If you have a module that uses children() and also runs a for() loop, the loop's index can conflict with $children indexing. I've had to wrap the for() loop inside a separate module, call it with children() as an argument, to make the scoping explicit.
Step-by-Step Debug Workflow
- Add
echo("myVar=", myVar);at every step inside the module, inside the loop, inside the child. - Check if
myVarappears in the console asundefineddespite being defined before the module call. - If you find it's undefined inside a
for()loop that you passed to a child, fix by passing the value:childModule(loopVar = i);. - 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;beforechildren().
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.
Workshop Alert: The 0.001 mm Fix
Always offset any difference() operation by at least 0.01 mm. Instead of cutting exactly at the surface, overshoot by a tiny amount. Example: difference() { cube(10); translate([5,5,-0.01]) cylinder(10.02, d=5); } the cylinder extends 0.01 mm below the cube base and 0.01 mm above the top. This guarantees a clean cut and no zero-thickness walls.
My Diagnostic Checklist
- Check for zero-thickness walls: Use
intersection_for()orminkowski()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 withpolyhedron, ensure all faces are wound counterclockwise as seen from outside. One flipped face breaks the mesh.
Troubleshooting Export Failure Matrix
- Issue: Slicer reports "non-manifold edges" at corners
- Cause: Overlapping unions with exact coplanar faces
- Fix: Add
0.001offset to one of the unions to create slight overlap - Issue: STL file is huge (500 MB), slicing takes forever
- Cause: Too many triangles from high
$fnon curved surfaces that are cut away - Fix: Reduce
$fnon internal geometries that won't be visible. Use$fa=12and$fs=2instead of$fn=100. - Issue: Slicer says "holes in mesh" but preview looks solid
- Cause:
difference()with atranslate()that creates a wall thickness of exactly zero (coplanar) - Fix: Make the cutting object slightly larger in the direction of the cut. E.g., if you cut a cylinder from a cube, extend the cylinder a hair beyond the cube bounds.
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.
Related Intel

DesignSpark Mechanical: Common Problems and Field Fixes
Troubleshoot DesignSpark Mechanical: fix mesh facet errors with chordal tolerance tuning, resolve direct modeling lock-ins, repair non-manifold solids, and stop GPU freezes.

AutoCAD Buying Guide: Shop-Floor Architecture & ROI
AutoCAD remains an essential industry benchmark for 2D drafting and DWG interoperability, but its $2,030 annual seat cost demands heavy AutoLISP workflow automation to justify capital investment over modern parametric suites.

FreeCAD vs Commercial CAD: Industrial Engineering Review
A comprehensive technical comparison of FreeCAD versus commercial CAD, evaluating the OpenCASCADE B-Rep kernel, topological naming resolution, and CalculiX FEA simulation.
