Use when an IFC file is rejected at the STEP-syntax stage of validation, a parser reports a string or header error, accented or non-ASCII text shows up as garbage characters, or the file fails before any schema check runs. Prevents writing an un-doubled apostrophe or backslash inside a STEP string, breaking a \X2\ or \X4\ escape with a missing \X0\ terminator, shipping mojibake from a UTF-8 versus Latin-1 mismatch, sending a malformed FILE_DESCRIPTION, FILE_NAME, or FILE_SCHEMA header, and hunting for a non-existent IfcFileDescription entity. Covers STEP Physical File string escaping failure modes, the three header entities and their EXPRESS, the empty-description rejection, a missing or lowercase FILE_SCHEMA identifier, a byte-order mark before the magic token, and why a stage-1 STEP syntax error blocks the file before schema validation. Keywords: IFC encoding error, STEP syntax error, string escaping, \X2\, \X4\, \X0\ terminator, doubled apostrophe, mojibake, character encoding mismatch, UTF-8, Latin-1, FIL
Use when an IFC file is rejected at the STEP-syntax stage of validation, a parser reports a string or header error, accented or non-ASCII text shows up as garbage characters, or the file fails before any schema check runs. Prevents writing an un-doubled apostrophe or backslash inside a STEP string, breaking a \X2\ or \X4\ escape with a missing \X0\ terminator, shipping mojibake from a UTF-8 versus Latin-1 mismatch, sending a malformed FILE_DESCRIPTION, FILE_NAME, or FILE_SCHEMA header, and hunting for a non-existent IfcFileDescription entity. Covers STEP Physical File string escaping failure modes, the three header entities and their EXPRESS, the empty-description rejection, a missing or lowercase FILE_SCHEMA identifier, a byte-order mark before the magic token, and why a stage-1 STEP syntax error blocks the file before schema validation. Keywords: IFC encoding error, STEP syntax error, string escaping, \X2\, \X4\, \X0\ terminator, doubled apostrophe, mojibake, character encoding mismatch, UTF-8, Latin-1, FILE_DESCRIPTION, FILE_NAME, FILE_SCHEMA, file_description, IfcFileDescription, byte-order mark, BOM, ISO-10303-21, implementation_level, "file will not open", "garbage characters in names", "IFC file rejected", "parser error on a string", "header is invalid", how do I fix a broken IFC header, why does my IFC file fail before validation.
license
MIT
compatibility
Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
IFC Encoding Issues (STEP Physical File)
Diagnose and fix the errors that break an IFC file at the STEP (ISO 10303-21)
text-encoding tier : un-doubled apostrophes and backslashes inside strings, broken
\X2\ and \X4\ escape sequences, mojibake from a character-set mismatch, a
malformed FILE_DESCRIPTION / FILE_NAME / FILE_SCHEMA header, and a byte-order
mark before the magic token. These errors are caught at validation stage 1 : the
file is rejected as text BEFORE any IFC entity, WHERE rule, or schema check runs.
For the STEP file structure and the full DEFINITION of the escape directives see
ifc-syntax-step-physical-file. For schema-tier errors (WHERE rules, abstract
entities, cardinality) see ifc-errors-schema-validation. This skill covers the
FAILURE MODES of the encoding layer only.
Quick Reference
STEP syntax is validation stage 1
The buildingSMART validation pipeline runs in stages. Stage 1 is STEP Syntax :
ISO 10303-21 file structure, the header, and string escaping. ALWAYS treat a
stage-1 failure as terminal : when the text cannot be parsed, NO later stage runs.
A schema WHERE-rule report is impossible until stage 1 passes.
Stage
Checks
This skill
1. STEP Syntax
ISO 10303-21 structure, header entities, string escaping, encoding
YES
2. Schema
entity types, cardinality, WHERE rules, abstract entities
NO : see ifc-errors-schema-validation
3+. Normative, industry practice
Gherkin rules, common-practice
NO
The header : three entities, fixed order, lowercase EXPRESS names
Every IFC file has a HEADER section with exactly three entities in this order:
file_description, file_name, file_schema. They are written with uppercase
keywords (FILE_DESCRIPTION, ...) in the file.
These are ISO 10303-21 STEP entities, NOT IFC entities. There is NO
IfcFileDescription, NO IfcFileName, NO IfcFileSchema. The EXPRESS names are
lowercase (file_description) ; the IFC schema (with its Ifc-prefixed,
PascalCase entities) does not begin until the section.
DATA
ENTITY file_description;
description : LIST [1:?] OF STRING (256);
implementation_level : STRING (256);
END_ENTITY;
ENTITY file_name;
name : STRING (256);
time_stamp : STRING (256);
author : LIST [1:?] OF STRING (256);
organization : LIST [1:?] OF STRING (256);
preprocessor_version : STRING (256);
originating_system : STRING (256);
authorization : STRING (256);
END_ENTITY;
ENTITY file_schema;
schema_identifiers : LIST [1:?] OF UNIQUE STRING (1024);
END_ENTITY;
The header EXPRESS is identical for IFC2x3, IFC4, and IFC4.3 : the guide states it
was "taken over from the ISO10303-21 STEP specification without any changes".
String escape directives (recap)
For diagnosis only. Full definitions are in ifc-syntax-step-physical-file.
Token
Meaning
''
one literal apostrophe inside a string
\\
one literal backslash inside a string
\X\HH
one code point U+0000 to U+00FF, exactly 2 hex digits
\X2\HHHH..\X0\
16-bit code points, multiples of 4 hex digits, terminated by \X0\
\X4\HHHHHHHH..\X0\
32-bit code points, multiples of 8 hex digits, terminated by \X0\
\S\
shift the next character by 128 into the ISO 8859 upper range
\PA\ ... \PI\
select the active ISO 8859 part for \S\
Core rules
ALWAYS double an apostrophe inside a STEP string : write O''Brien, never
O'Brien. A lone ' ends the string and breaks the parser.
ALWAYS double a literal backslash : write C:\\path, never C:\path. A lone
\ starts an escape directive the parser then fails to complete.
ALWAYS terminate \X2\ and \X4\ with \X0\. An unterminated escape consumes
the rest of the string.
ALWAYS supply at least one string in FILE_DESCRIPTION description, author,
organization, and FILE_SCHEMA : each is LIST [1:?]. An empty list ()
violates the cardinality and rejects the file.
ALWAYS write the FILE_SCHEMA identifier in uppercase : IFC4, never ifc4.
NEVER place a byte-order mark or any character before ISO-10303-21;. The file
MUST begin with that exact token.
NEVER look for IfcFileDescription : the header uses STEP entities, not IFC
entities.
What validation category does the report name ?
├─ "STEP Syntax" / "syntax" / a line-and-column parser error
│ -> stage 1. This skill. No schema check has run yet.
└─ "Schema" / "Compliance" / a WHERE-rule or entity name
-> stage 2. The text parsed cleanly. See ifc-errors-schema-validation.
Which schema identifier belongs in FILE_SCHEMA
What schema was the file authored against ?
├─ IFC2x3 -> 'IFC2X3'
├─ IFC4 -> 'IFC4'
└─ IFC4.3 -> 'IFC4X3_ADD2' (the buildingSMART validation service identifier;
earlier development files used 'IFC4X3_RC...')
Patterns
Pattern 1 : fix an un-doubled apostrophe or backslash
A STEP string is delimited by single quotes. Inside the string, a literal
apostrophe MUST be written as two apostrophes and a literal backslash as two
backslashes. A single ' closes the string early ; a single \ is read as the
start of an escape directive.
Fix : double every literal apostrophe and backslash in every string value. A
name Conference Room 'A' becomes 'Conference Room ''A'''. A Windows path
C:\Models\a.ifc inside FILE_NAME becomes 'C:\\Models\\a.ifc'. NEVER leave a
lone ' or \ inside string content.
Pattern 2 : fix a broken \X2\ or \X4\ escape sequence
\X2\ introduces 16-bit code points : the hex payload MUST be a multiple of FOUR
hex digits and MUST end with \X0\. \X4\ introduces 32-bit code points : a
multiple of EIGHT hex digits, also ended with \X0\. An escape that is missing
its \X0\, or has a hex-digit count that is not a clean multiple, is malformed :
the parser keeps consuming characters and the string fails.
Fix:
Add the missing \X0\ terminator : '\X2\00E9' becomes '\X2\00E9\X0\'.
Pad or correct the hex payload to a multiple of 4 (for \X2\) or 8 (for
\X4\) hex digits. The letter e-acute is U+00E9, so the \X2\ payload is the
4-digit 00E9, not E9.
Verify each code point : \X2\03C0\X0\ is the Greek pi (U+03C0).
Pattern 3 : fix mojibake (a character-set mismatch)
The robust, interoperable rule for STEP strings : ALWAYS encode every non-ASCII
character with a control directive (\X\, \X2\, \X4\), so the string body is
pure 7-bit ASCII and no reader can misinterpret the bytes. ISO 10303-21 edition 3
(2016) does permit raw UTF-8 octets in the exchange structure, but a file that
relies on that fails in any consumer built against an earlier Part 21 edition.
NEVER ship raw non-ASCII octets when broad interoperability is required.
Fix : re-export the file with control-directive escaping for all non-ASCII text,
or, if the bytes are intact but mislabelled, re-encode the file to the character
set the consumer expects. A related cause is a stray byte-order mark : see
Pattern 4.
Pattern 4 : fix a malformed header
The HEADER section MUST contain file_description, file_name, and
file_schema, in that order, between HEADER; and ENDSEC;. Common stage-1
failures:
Empty description : FILE_DESCRIPTION((),'2;1'). The description attribute is
LIST [1:?] ; an empty list violates the lower bound and rejects the file. Fix
: supply at least one string, for example
FILE_DESCRIPTION(('ViewDefinition [CoordinationView]'),'2;1').
Empty author or organization list in FILE_NAME : both are LIST [1:?].
Fix : supply at least one string ; an unknown value is an empty STRING (''),
NOT an empty list ().
A byte-order mark or whitespace before ISO-10303-21;. The file MUST start
with that exact token. Fix : strip the leading BOM bytes (EF BB BF for
UTF-8).
Header entities out of order or missing. Fix : restore the order
file_description, file_name, file_schema.
The implementation_level (second FILE_DESCRIPTION attribute) is the string
'2;1' for IFC files. ALWAYS keep it '2;1'.
Pattern 5 : fix a missing or wrong FILE_SCHEMA
FILE_SCHEMA carries schema_identifiers, a LIST [1:?] of schema-name strings.
A reader dispatches its parser on this value. If it is missing, empty, or names a
schema the reader does not support, the file is rejected at stage 1 or stage 2.
Two version traps:
Lowercase identifier. The guide states a schema name's small letters MUST be
converted to capitals : only capital letters occur in the string. 'ifc4' is
wrong ; write 'IFC4'.
Wrong identifier for the actual content. A file whose entities are IFC4 but
whose FILE_SCHEMA says 'IFC2X3' confuses the reader. Fix : set the
identifier to match the schema the data was authored against : 'IFC2X3',
'IFC4', or 'IFC4X3_ADD2'.
Fix : FILE_SCHEMA(('IFC4')); with one uppercase identifier matching the data.
Pattern 6 : the lowercase-header-entity trap
Code or a query that looks for IfcFileDescription, IfcFileName, or
IfcFileSchema finds nothing, because those entities do not exist. The header is
defined by ISO 10303-21, not by the IFC schema. Its three entities are the
lowercase STEP entities file_description, file_name, file_schema.
Fix : read header data through the STEP parser's header API, not by querying the
IFC entity population. The Ifc-prefixed entities (IfcProject, IfcWall, ...)
exist ONLY in the DATA section. ALWAYS keep the two namespaces separate : STEP
header entities are lowercase and un-prefixed ; IFC data entities are PascalCase
and Ifc-prefixed.
Reference Links
references/methods.md : the three header entities in full EXPRESS, the escape
directive table, schema identifiers per version, the encoding rule per Part 21
edition.
references/examples.md : broken header and string fragments next to their
fixes.
references/anti-patterns.md : the encoding mistakes and why each one is wrong.
Related skills
ifc-syntax-step-physical-file : the STEP file structure and the full escape
directive definitions.
ifc-errors-schema-validation : stage-2 WHERE-rule, cardinality, and
abstract-entity errors.
ifc-errors-version-mismatch : a FILE_SCHEMA that disagrees with the entities.
Verified sources
The file_description, file_name, and file_schema EXPRESS definitions, the
implementation_level value, and the header example are verified verbatim
2026-05-20 against the buildingSMART Implementation Guide for IFC Header Data
v1.0.2. The string escape directives and the UTF-8 encoding rule are verified
against ISO 10303-21 edition 3 (steptools.com reference). Both sources are listed
in SOURCES.md.
