Topological naming problem
Introduction
The topological naming problem in FreeCAD refers to the issue of a shape changing its internal name after a modelling operation (pad, cut, union, chamfer, fillet, etc.) is performed. This will result in other parametric features that depend on that shape to break or be incorrectly computed. This issue affects all objects in FreeCAD but is especially notable when building solids with the PartDesign Workbench, and when dimensioning those solids with the
TechDraw Workbench.
- In
PartDesign, if a feature is supported on a face (or edge or vertex), the feature may break if the underlying solid changes size or orientation, as the original face (or edge or vertex) may be internally renamed.
- In
TechDraw, if a dimension is measuring the length of a projected edge, the dimension may break if the 3D model is changed, as the vertices may be renamed thus changing the measured edge.
The topological naming issue is a complex problem in CAD modelling that stems from the way the internal FreeCAD routines handle updates of the geometrical shapes created with the OCCT kernel. This problem is not unique to FreeCAD. It is generally present in CAD software, but most other CAD software has heuristics to reduce the impact of the problem on users.
Starting with FreeCAD 0.19 there are ongoing development efforts to improve the core handling of shapes in order to reduce the impact of these issues. The naming algorithm described in forum thread Topological Naming, My Take is designed to reduce manual effort, sometimes by automatically fixing up problems, and other times presenting a likely solution, or at least clearly showing what caused the problem. The first stable release of FreeCAD to feature this new naming algorithm will be 1.0. Over time, this algorithm will be applied to more parts of FreeCAD, and more automatic and assisted repair will be added in later versions.
The topological naming problem most often affects and confuses new users of FreeCAD. In PartDesign, the user is advised to follow the best practices discussed in the feature editing page. Use of supporting datum objects like planes and local coordinate systems is strongly recommended to produce models that aren't easily subject to such topological errors. In TechDraw, the user is advised to add dimensions only when the 3D model is complete and won't be modified further.
Example
1. In the PartDesign Workbench, create a
PartDesign Body, then use
PartDesign NewSketch and select the XY plane to draw the base sketch; then perform a
PartDesign Pad to create a first solid.
2. Select the top face of the previous solid, and then use PartDesign NewSketch to draw another sketch; then perform a second pad.
![]() |
![]() |
3. Select the top face of the previous extrusion, and once again create a sketch, and a pad.
4. Now, double click the second sketch, and modify it so that its length is along the X direction; doing this will recreate the second pad. The third sketch and pad will stay in the same place.
![]() |
![]() |
5. Now, double click the second sketch again, and adjust its points so that a portion of it is outside the limits defined by the first pad. By doing this, the second pad will recompute correctly, however, when looking at the tree view, an error will be indicated in the third pad.
![]() |
![]() |
6. By making visible the third sketch and pad, it is clear that the computation of the new solid did not proceed correctly. The third sketch, instead of being supported by the top face of the second pad, appears in a strange place, with its normal oriented towards the X direction. This results in an invalid pad, as this pad would be disconnected from the rest of the PartDesign Body, which is not allowed.
The problem appears to be that when the second sketch was modified, the top face of the second pad was renamed from Face13
to Face14
. The third sketch is attached to Face13
as it originally was, but since this face is now on the side (not at the top), the sketch follows its orientation and now is incorrectly positioned.
![]() |
![]() |
7. To fix the issue, the third sketch should be mapped to the top face again. Select the sketch, click on the ellipsis (three dots) next to the DataMap Mode property, and choose the top face of the second pad again. Then the sketch moves to the top of the existing solid, and the third pad is generated without issues.
![]() |
![]() |
Remapping a sketch in this way can be done every time there is a topological naming error, however, this may be tedious if the model is complicated and there are many such sketches that need to be adjusted.
Solution

The dependency graph is a tool that is helpful to observe the relationships between the different bodies in the document. Using the original modelling workflow reveals the direct relationship that exists between the sketches and the pads. Like a chain, it is easy to see that this direct dependence will be subject to topological naming problems if any of the links in the sequence changes.
As explained on the feature editing page, a solution to this problem is to support sketches not on faces, but on the main planes of the PartDesign Body's Origin, or on datum planes attached to those main planes. Using datum planes to support a single sketch, as is described below, is actually not necessary as the sketch itself can be directly attached to a main plane and has the same offset options as a datum plane. But using datum planes can make sense when positioning multiple sketches.
1. Select the origin of the PartDesign Body and make sure that it is visible. Then select the XY plane, and click on PartDesign Plane. In the attachment offset dialog, give it an offset in the Z direction so that the datum plane is coplanar with the top face of the first pad.
2. Repeat the process but this time add a larger offset so that the second datum plane is coplanar with the top face of the second pad.
![]() |
![]() |
3. Select the second sketch, click on the ellipsis next to the DataMap Mode property, and then select the first datum plane. The datum plane is already offset from the body's XY plane, so no further Z offset is required for the sketch.
4. Repeat the process with the third sketch, and select the second datum plane as support. Again, no further Z offset is necessary.
5. The dependency graph now shows that the sketches and pads are supported by the datum planes. This model is more stable as each sketch can be modified essentially independently from each other.
6. Double click the second sketch and modify the shape. The second pad should update immediately without causing topological problems with the third sketch and the third pad.
7. In fact, every sketch can be modified without interfering with each other's pads. As long as the pads have sufficient extrusion length, so that they touch and form a contiguous solid, the entire body will be valid.
Tradeoffs
Adding datum objects is more work for the user but ultimately produces more stable models that are less subject to the topological naming problem.
Naturally, datum objects can be created before any sketches are drawn, and pads are produced. This may be helpful to visualize the approximate shape and dimensions of the final body.
Datum planes can also be based on other datum planes. This creates a chain of dependencies that could also result in topological problems; however, since datum planes are very simple objects, the risks of having these issues is less than if the face of a solid object is used as support.
Datum objects, points, lines, planes, and coordinate systems, may also be useful as reference geometry, that is, as visual aids to show the important features in the model, even if no sketch is directly attached to them.
Topological naming algorithm
Realthunder's topological naming algorithm selected to reduce the impact of this problem has been widely described as "fixing the topological naming problem," which has unintentionally misled many users into thinking that it will no longer be helpful to use techniques like datums, explicit sketch placement, and Feature editing to make models more stable. The algorithm is not intended to fix every failure introduced by topological naming ambiguity. Rather, it has three purposes.
- The first and most important purpose is, whenever possible, to identify broken references from topological changes and display an error to the user. Instead of having to work through a series of operations to find the first operation that diverges from the design intent, the operation that changes the names will normally be flagged with an error, making it much easier to manually fix model problems introduced by changes to operations or parameters.
- Sometimes, FreeCAD will be able to identify a likely fix for a broken reference, so that when the user is manually fixing up the flagged broken reference, a candidate will be presented for them to accept or change. A common example of this is dress-up operations like fillets and chamfers, where user might have to to edit the operation and either accept the proposed replacement feature selection or change it to correct it.
- In some cases, FreeCAD will be able to automatically resolve the broken reference, because enough information about the reference is stored to have high confidence that the replacement is correct. For example, when sketching directly on a face, the algorithm will frequently (but not always) correctly repair the reference to the face when the underlying geometry is changed parametrically. (When changing the structure, such as by adding or deleting operations in the middle of a Part Design Body, this kind of automatic repair will be less likely.) However, FreeCAD will do this only with high confidence in the correctness of the repair, because an incorrect automatic repair may re-introduce the problem of having to hunt for where a problem was introduced in order to repair a model after a modification. First, do no harm.
The goal for FreeCAD 1.0 is that the implementation of this algorithm in the official FreeCAD release has reached feature parity with Realthunder's "Linkstage 3" fork, where he originally developed the algorithm, as of the time the integration work started. There are new FreeCAD features that could use the algorithm but do not yet, and there will always be more opportunities to add candidate fixes and automatic repair. The initial work has provided a framework to use for these additional improvements over time, both in core FreeCAD and in Addons.
Links
- PartDesign Fillet - Topological naming
- Topological Naming, My Take: a possible solution, by realthunder.
- Topological Naming Project: idea to solve the problem, by ickby.
- Topological data scripting
- Feature editing: contains alternate advice for stable modelling techniques.
- Clarifying and expanding "Topological Naming Problem" documentation: Clarifying expectations for Realthunder's topological naming algorithm selected for FreeCAD 1.0.
Videos
- Why do my FreeCAD models break? - "Topological Naming Problem": A Video explanation of the underlying issues of Topological naming problem
- FreeCAD Is Fundamentally Broken! - Now what... Help Me Decide...: A Maker Tales Video

- Getting started
- Installation: Download, Windows, Linux, Mac, Additional components, Docker, AppImage, Ubuntu Snap
- Basics: About FreeCAD, Interface, Mouse navigation, Selection methods, Object name, Preferences, Workbenches, Document structure, Properties, Help FreeCAD, Donate
- Help: Tutorials, Video tutorials
- Workbenches: Std Base, Assembly, BIM, CAM, Draft, FEM, Inspection, Material, Mesh, OpenSCAD, Part, PartDesign, Points, Reverse Engineering, Robot, Sketcher, Spreadsheet, Surface, TechDraw, Test Framework
- Hubs: User hub, Power users hub, Developer hub
- Pages: Insert Default Page, Insert Page using Template, Update template fields, Redraw Page, Print All Pages, Export Page as SVG, Export Page as DXF
- Views:
- TechDraw views: Insert View, Insert Broken View, Insert Section View, Insert Complex Section View, Insert Detail View, Insert Projection Group, Insert Clip Group, Insert SVG Symbol, Insert Bitmap Image, Share View, Turn View Frames On/Off, Project Shape
- Views from other workbenches: Insert Active View, Insert Draft Workbench Object, Insert BIM Workbench Object, Insert Spreadsheet View
- Stacking: Move view to top of stack, Move view to bottom of stack, Move view up one level, Move view down one level
- Dimensions: Insert Dimension, Insert Length Dimension, Insert Horizontal Dimension, Insert Vertical Dimension, Insert Radius Dimension, Insert Diameter Dimension, Insert Angle Dimension, Insert 3-Point Angle Dimension, Insert Area Annotation, Create Arc Length Dimension, Insert Horizontal Extent Dimension, Insert Vertical Extent Dimension, Create Horizontal Chain Dimensions, Create Vertical Chain Dimensions, Create Oblique Chain Dimensions, Create Horizontal Coordinate Dimensions, Create Vertical Coordinate Dimensions, Create Oblique Coordinate Dimensions, Create Horizontal Chamfer Dimension, Create Vertical Chamfer Dimension, Insert Balloon Annotation, Insert Axonometric Length Dimension, Insert Landmark Dimension, Dimension Repair, Link Dimension to 3D Geometry
- Hatching: Hatch Face using Image File, Apply Geometric Hatch to Face,
- Annotations: Insert Annotation, Add Leaderline to View, Insert Rich Text Annotation, Add Cosmetic Vertex, Add Midpoint Vertices, Add Quadrant Vertices, Add Centerline to Faces, Add Centerline between 2 Lines, Add Centerline between 2 Points, Add Cosmetic Line Through 2 points, Add Cosmetic Circle, Change Appearance of Lines, Show/Hide Invisible Edges, Add Welding Information to Leader, Add Surface Finish Symbol, Add Hole or Shaft Tolerances
- Extensions:
- Attributes and modifications: Select Line Attributes, Cascade Spacing and Delta Distance, Change Line Attributes, Extend Line, Shorten Line, Lock/Unlock View, Position Section View, Position Horizontal Chain Dimensions, Position Vertical Chain Dimensions, Position Oblique Chain Dimensions, Cascade Horizontal Dimensions, Cascade Vertical Dimensions, Cascade Oblique Dimensions, Calculate the area of selected faces, Calculate the arc length of selected edges, Customize format label
- Centerlines and threading: Add Circle Centerlines, Add Bolt Circle Centerlines, Add Cosmetic Thread Hole Side View, Add Cosmetic Thread Hole Bottom View, Add Cosmetic Thread Bolt Side View, Add Cosmetic Thread Bolt Bottom View, Add Cosmetic Intersection Vertex(es), Add an offset vertex, Add Cosmetic Circle, Add Cosmetic Arc, Add Cosmetic Circle 3 Points, Add Cosmetic Parallel Line, Add Cosmetic Perpendicular Line
- Dimensions: Insert '⌀' Prefix, Insert '□' Prefix, Insert 'n×' Prefix, Remove Prefix, Increase Decimal Places, Decrease Decimal Places
- Miscellaneous: Remove Cosmetic Object
- Additional: Line Groups, Templates, Hatching, Geometric dimensioning and tolerancing, Preferences
- Structure tools: Part, Group
- Helper tools: Create body, Create sketch, Attach sketch, Edit sketch, Validate sketch, Check geometry, Create a shape binder, Create a sub-object(s) shape binder, Create a clone, Create a datum plane, Create a datum line, Create a datum point, Create a local coordinate system
- Modeling tools:
- Additive tools: Pad, Revolution, Additive loft, Additive pipe, Additive helix, Additive box, Additive cylinder, Additive sphere, Additive cone, Additive ellipsoid, Additive torus, Additive prism, Additive wedge
- Subtractive tools: Pocket, Hole, Groove, Subtractive loft, Subtractive pipe, Subtractive helix, Subtractive box, Subtractive cylinder, Subtractive sphere, Subtractive cone, Subtractive ellipsoid, Subtractive torus, Subtractive prism, Subtractive wedge
- Boolean: Boolean operation
- Dress-up tools: Fillet, Chamfer, Draft, Thickness
- Transformation tools: Mirrored, Linear Pattern, Polar Pattern, Create MultiTransform, Scaled
- Extras: Sprocket, Involute gear, Shaft design wizard
- Context menu: Set tip, Move object to other body, Move object after other object, Appearance, Color per face
- Preferences: Preferences, Fine tuning
- Primitives: Box, Cylinder, Sphere, Cone, Torus, Tube, Create primitives, Shape builder
- Creation and modification: Create sketch, Extrude, Revolve, Mirror, Scale, Fillet, Chamfer, Make face from wires, Ruled Surface, Loft, Sweep, Section, Cross sections, 3D Offset, 2D Offset, Thickness, Projection on surface, Color per face
- Boolean: Make compound, Explode compound, Compound Filter, Boolean, Cut, Union, Intersection, Connect objects, Embed object, Cutout for object, Boolean fragments, Slice apart, Slice to compound, Boolean XOR, Check geometry, Defeaturing
- Other tools: Import CAD file, Export CAD file, Box selection, Create shape from mesh, Create points object from geometry, Convert to solid, Reverse shapes, Create simple copy, Create transformed copy, Create shape element copy, Refine shape, Attachment
- Preferences: Preferences, Fine tuning