How to Solve FreeCAD Topological Naming Issues

The Topological Naming Problem (TNP) occurs in FreeCAD when altering an early sketch causes internal geometric references—such as Face1 or Edge3—to be re-indexed, which in turn breaks downstream operations attached to those elements. This guide provides actionable methods to avoid TNP during the design phase, workflows to decouple sketches from generated geometry, and step-by-step instructions for repairing broken models when base sketches are altered.

Understand Why the Issue Occurs

In FreeCAD, features generated from sketches (like pads or pockets) produce faces, edges, and vertices that are labeled sequentially by the underlying geometric kernel. When you edit a base sketch by adding, deleting, or altering geometry, the order and total count of the resulting faces change. Any downstream feature attached directly to a generated face (e.g., "Face4") will either attach to the wrong face or fail completely because that specific index no longer represents the original geometry.

Use Datum Planes Instead of Solid Faces

The most effective way to prevent TNP is to avoid mapping new sketches directly onto the faces of a 3D solid. Instead, use Datum Planes:

  1. Select the base coordinate system planes (XY, XZ, or YZ) or an immutable reference feature.
  2. Create a Datum Plane from the Part Design workbench.
  3. Adjust the plane's position using the Attachment Offset properties (X, Y, Z translations and rotations).
  4. Attach your new sketch to this Datum Plane rather than the face of the solid.

Because the Datum Plane references the global coordinate system, changes to preceding solid geometry will not affect the sketch's placement.

Implement Master Sketches (Skeleton Modeling)

Centralize your model's critical dimensions using skeleton sketches:

  1. Create one or more base sketches at the very beginning of the tree on standard origin planes.
  2. Draw the primary framework, bounding boxes, and alignment lines of your design.
  3. Reference these primary sketches across subsequent sketches using the External Geometry tool or using the Spreadsheet Workbench with aliases.
  4. If base dimensions change, edit the master sketch; downstream solid features will adjust their size without reordering generated face references.

Apply Dress-Up Features at the Very End

Chamfers, fillets, drafts, and thread features significantly alter edge and face numbering. Never attach sketches or downstream features to geometry created after applying a dress-up feature. Keep all fillets and chamfers as the final operations at the bottom of the Part Design tree.

How to Repair Broken Sketches After Editing a Base Sketch

If you have already modified a base sketch and downstream features have broken, resolve the broken dependencies sequentially from top to bottom:

  1. Re-link the Sketch Support:
    • Select the broken sketch in the tree view.
    • Go to the Data tab in the Property View.
    • Locate the Map Mode (or Attachment) property and click the ellipsis (...) button.
    • Clear the missing or incorrect reference and select the correct face or Datum Plane.
    • Set the attachment mode (typically "FlatFace") and click OK.
  2. Fix Missing External Geometry:
    • Open the broken sketch in the Sketcher workbench.
    • Missing external geometry references will appear in magenta or trigger an error message.
    • Delete the broken external reference lines.
    • Re-import the external geometry from the updated solid or link to an origin plane/master sketch.
    • Re-apply any lost constraints to the newly selected references.
  3. Recompute the Model:
    • Close the sketch.
    • Press Ctrl + R (or click the Recompute button) to evaluate the model tree.
    • Move to the next broken feature down the tree and repeat the process.

Upgrade to FreeCAD 1.0 or Later

Beginning with FreeCAD 1.0, the integrated Topological Naming Algorithm (originally developed under the Ondsel project) automatically tracks and remaps geometric elements across edits. While upgrading minimizes errors caused by simple sketch modifications, adhering to stable modeling habits—such as using Datum geometry and avoiding face attachments—remains the industry standard for parametric CAD reliability.