snappyHexMesh: Common Errors and How to Fix Them

snappyHexMesh is the most powerful mesher in OpenFOAM, but it is also notoriously tricky to configure. Small errors in the snappyHexMeshDict, a bad STL file, or wrong location settings can produce a mesh that fails checkMesh, loses layers, or crashes entirely. This guide covers the full dict structure, the most common error messages, and how to fix each one.

By CFDpilot · Updated April 2026

1. snappyHexMeshDict structure

snappyHexMesh runs in up to three phases, each controlled by a switch in the dict:

// system/snappyHexMeshDict — top-level phase switches
castellatedMesh  true;   // phase 1: refine and cut cells
snap             true;   // phase 2: move surface vertices onto geometry
addLayers        true;   // phase 3: grow prism layers on walls

When debugging, set addLayers false first and get a clean castellated+snapped mesh before worrying about layers. Layers are the most failure-prone phase.

A typical snappyHexMesh workflow is: 1) create the background hex mesh with blockMesh, 2) run surfaceFeatureExtract to extract .eMesh from STL, 3) run snappyHexMesh, 4) verify with checkMesh -latestTime, 5) rename or copy the final time directory to constant/polyMesh. Always place your STL files in constant/triSurface/.

Geometry block

geometry
{
    myGeometry.stl
    {
        type    triSurfaceMesh;
        name    body;  // used as patch name in the mesh
        regions
        {
            inlet_surface  { name inlet; }
            outlet_surface { name outlet; }
        }
    }

    refinementBox
    {
        type    searchableBox;
        min     (-1 -1 -1);
        max     (2 1 1);
    }
}

castellatedMeshControls

castellatedMeshControls
{
    maxLocalCells           1000000;
    maxGlobalCells          2000000;
    minRefinementCells      10;
    maxLoadUnbalance        0.10;
    nCellsBetweenLevels     3;  // buffer cells between refinement levels

    features
    (
        {
            file    "myGeometry.eMesh";
            level   2;
        }
    );

    refinementSurfaces
    {
        body
        {
            level   (2 3);  // (min max) refinement levels
            patchInfo { type wall; }
        }
    }

    refinementRegions
    {
        refinementBox
        {
            mode    inside;
            levels  ((1E15 1));  // level 1 everywhere inside box
        }
    }

    locationInMesh  (0 0 0.5);  // CRITICAL: must be inside the fluid domain
    allowFreeStandingZoneFaces true;
}

snapControls

snapControls
{
    nSmoothPatch        3;
    tolerance           2.0;
    nSolveIter          30;
    nRelaxIter          5;
    nFeatureSnapIter    10;
    implicitFeatureSnap false;
    explicitFeatureSnap true;  // requires .eMesh file
    multiRegionFeatureSnap false;
}

addLayersControls

addLayersControls
{
    relativeSizes   true;  // layer thickness relative to local cell size
    layers
    {
        body
        {
            nSurfaceLayers  5;
        }
    }
    expansionRatio      1.2;
    finalLayerThickness 0.3;
    minThickness        0.1;
    nGrow               0;
    featureAngle        130;   // surfaces with angle > this are treated as features
    nRelaxIter          3;
    nSmoothSurfaceNormals 1;
    nSmoothNormals      3;
    nSmoothThickness    10;
    maxFaceThicknessRatio 0.5;
    maxThicknessToMedialRatio 0.3;
    minMedianAxisAngle  90;
    nBufferCellsNoExtrude 0;
    nLayerIter          50;
}

2. Surface feature extraction

For explicitFeatureSnap true, you must pre-extract the edge features from your STL file using surfaceFeatureExtract (older versions) or surfaceFeatures (v2012+). This creates a .eMesh file referenced in the features block.

// system/surfaceFeatureExtractDict (pre-v2012)
myGeometry.stl
{
    extractionMethod    extractFromSurface;
    extractFromSurfaceCoeffs
    {
        includedAngle   150;  // extract edges sharper than 30° (180-150)
    }
    writeObj    yes;
}

Run it with: surfaceFeatureExtract. This produces constant/triSurface/myGeometry.eMesh.

In OpenFOAM v2012+, the equivalent utility is called surfaceFeatures and uses system/surfaceFeaturesDict. The output is the same .eMesh format. Always verify the extracted features by loading the .obj file in ParaView — you should see edge lines on the expected sharp features only.

3. Parallel snappyHexMesh

For large meshes (above ~5 million cells), running snappyHexMesh in parallel is essential. The workflow is: decompose the background mesh with decomposePar, then run snappy in parallel, then reconstruct.

// Run snappyHexMesh in parallel (8 cores)
blockMesh
decomposePar
mpirun -np 8 snappyHexMesh -overwrite -parallel
reconstructParMesh -constant

Use -overwrite to write directly to the constant/polyMesh directory instead of creating numbered time directories. Note that reconstructParMesh is needed (not reconstructPar) for mesh reconstruction.

For very large cases, disable writeInterval intermediate meshes by setting runTimeModifiable false and checking that the memory per core is adequate. Each snappyHexMesh phase (castellated, snap, addLayers) writes a separate time directory in parallel mode.

4. Common error: "patches not found"

If snappyHexMesh prints Cannot find patch 'inlet' in mesh or similar, the patch name in snappyHexMeshDict does not match any named region in your STL file. STL regions are case-sensitive. Open your STL file and verify the solid name matches exactly what you reference in the regions block of the geometry section. Alternatively, export your geometry as a single STL per patch and list each file separately in the geometry block.

5. Common error: "layer addition failed"

This happens when snappyHexMesh cannot grow prismatic layers in a region because the cells are too compressed, the surface has high curvature, or two surfaces are too close together. Strategies to fix it:

• Reduce nSurfaceLayers to 3 or even 2 and check if layers form
• Reduce finalLayerThickness to 0.1 or 0.2
• Increase minThickness (e.g. 0.01) — this allows snappy to give up on thin patches and still produce the rest
• Increase maxThicknessToMedialRatio to 0.5 or 0.6 for tight geometries
• Check the base mesh resolution — if the cells touching the wall are too large, there is no room for layers

6. Common error: locationInMesh inside geometry

The locationInMesh point tells snappyHexMesh which side of the geometry is the fluid domain. If this point falls inside a solid body, snappyHexMesh will remove the fluid cells and keep the solid region — producing an empty or inverted mesh. Always verify that your locationInMesh coordinate is clearly inside the fluid domain, not touching any surface.

7. Running checkMesh after snappy

Always run checkMesh after snappyHexMesh completes. Look for:

• Max non-orthogonality > 70 — reduce refinement jump between levels (increase nCellsBetweenLevels)
• Max skewness > 4 — improve STL surface quality; use fewer layer levels
• Negative cell volumes — layers have collapsed; disable layers and rebuild
• Mesh outside domain — locationInMesh or background mesh size error

// Run checkMesh on the snappy output time directory
checkMesh -latestTime

8. Refinement regions

Use searchableBox, searchableSphere, or searchableCylinder geometry objects in the refinementRegions block to add volumetric refinement in specific areas (near the body wake, around the inlet jet, etc.) without refining the entire mesh.

refinementRegions
{
    wakeRegion  // name defined in geometry{} block
    {
        mode    inside;
        levels  ((1E15 2));  // level 2 refinement everywhere inside
    }
}

9. Background mesh sizing — blockMeshDict guidelines

The background hex mesh from blockMesh determines the base cell size from which snappyHexMesh refines. Sizing it correctly is critical: too coarse and you need too many refinement levels (expensive), too fine and the background mesh itself is expensive before refinement.

A good rule: the base cell size should be roughly the size of the domain divided by 20–50 in each direction. Then use refinement levels to achieve the target near-wall cell size. Each refinement level halves the cell size. For example, if your base cell is 0.1 m and you need 0.00625 m at the wall, you need 4 levels of refinement (0.1 / 2^4 = 0.00625).

// system/blockMeshDict — simple background box
vertices
(
    (-2 -1 -1)
    (10 -1 -1)
    (10  3 -1)
    (-2  3 -1)
    (-2 -1  1)
    (10 -1  1)
    (10  3  1)
    (-2  3  1)
);

blocks
(
    hex (0 1 2 3 4 5 6 7) (120 40 20) simpleGrading (1 1 1)
    // 120 cells in x (12m / 0.1m), 40 in y (4m / 0.1m), 20 in z (2m / 0.1m)
);

Keep the background mesh cells as close to cubic as possible (equal number of cells per unit length in each direction). Highly anisotropic background cells produce poor snapped meshes.

10. STL file quality requirements

snappyHexMesh is sensitive to STL geometry quality. Common STL problems that cause snappy failures:

• Non-manifold edges — edges shared by more than two faces. Use surfaceCheck to detect them.
• Self-intersecting surfaces — surfaces that pass through themselves. Fix in CAD before exporting.
• Open surfaces — surfaces with boundary edges (holes). snappy needs a watertight surface to define inside/outside.
• Wrong normals — STL normals pointing inward instead of outward. Can cause locationInMesh to be misidentified as inside.

// Check STL quality before running snappyHexMesh
surfaceCheck constant/triSurface/myGeometry.stl

If surfaceCheck reports open edges or self-intersections, fix the geometry before proceeding. Tools like Blender, FreeCAD, or Meshmixer can repair STL files.