ifc-errors-broken-references

name	ifc-errors-broken-references
description	Use when an IFC file has a reference that points nowhere, a parser crashes on an unresolved #id, or an element silently disappears from a downstream tool (no material, no property set, no spatial location) even though the file is schema-valid. Prevents treating a dangling #id and a missing INVERSE link as the same bug, trusting a "valid" verdict to mean the model is complete, and creating a relationship with the Relating and Related roles swapped. Covers the reference-graph nature of the STEP instance model, dangling and wrong-typed #id references, missing IfcRel* relationship entities, why a missing INVERSE attribute is a silent failure, detection scans, and fixes, across IFC2x3, IFC4 and IFC4.3 including the IfcBuildingElement to IfcBuiltElement rename. Keywords: dangling reference, broken #id, unresolved reference, missing INVERSE link, IfcRelContainedInSpatialStructure, IfcRelAssociatesMaterial, IfcRelDefinesByProperties, orphan element, element has no material, element has no property set, element not in spatial structure, ContainedInStructure, HasAssociations, IsDefinedBy, wrong-typed reference, reference graph, forward reference, "object not found", "by_id failed", "nothing shows for this wall", "valid file but element missing", how do I fix a broken reference, what is a dangling reference in IFC.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

IFC Broken References

Diagnose and fix two distinct reference faults in an IFC instance file : a dangling reference (a #id token that resolves to nothing or to the wrong entity type) and a missing INVERSE link (a relationship entity that was never created, so an element has no material, no property set, or no spatial location). The first is a hard failure a parser or validator catches. The second is a silent failure no schema check ever reports.

For STEP syntax and header errors see ifc-errors-encoding-issues. For EXPRESS WHERE and global-rule violations see ifc-errors-schema-validation. For loading and traversing a model see ifc-impl-reading-parsing.

Quick Reference

An IFC file is a reference graph

A STEP Physical File (.ifc) is a flat list of numbered instances. Every line defines one instance : #id=ENTITY(attr,attr,...). Any attribute that names another instance does so with a #id token. The whole file is therefore a directed graph : instances are nodes, #id tokens are edges.

#42=IFCWALL('1a2B...',#5,'Wall-01',$,$,#88,#120,'TAG-42',$);
                       ^^                ^^^ ^^^^
                       OwnerHistory      ObjectPlacement, Representation

Two facts drive every bug in this skill (verified, ISO 10303-21) :

1. References may be forward (the referenced #id is defined later in the file) or backward. A conformant reader MUST index the entire file before resolving any reference. NEVER assume a reference target appears earlier.
2. Only explicit attributes are serialized. INVERSE and DERIVE attributes are absent from every encoding ; a reader recomputes them by indexing the forward references. A relationship therefore exists ONLY if its IfcRel* instance was written. No instance, no link.

Two fault classes : never conflate them

Fault	What it is	Detected by	Severity
Dangling reference	A #id token resolves to no instance, or to an instance of the wrong entity type	Parser (crash / by_id error) or schema type check	HARD : file rejected or load aborts