ifc-errors-encoding-issues

name	ifc-errors-encoding-issues
description	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 DATA section.

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.

Decision Trees

Which encoding error is this

Symptom ?
├─ rejected at "STEP Syntax" stage, parser error mid-string
│   ├─ an apostrophe inside a string is not doubled      -> Pattern 1
│   ├─ a lone backslash is not doubled                   -> Pattern 1
│   └─ a \X2\ or \X4\ has no \X0\ or wrong hex count     -> Pattern 2
├─ file parses but accented text shows as garbage (é, £, )
│   -> character-set mismatch (mojibake)                 -> Pattern 3
├─ rejected, error names the HEADER
│   ├─ FILE_DESCRIPTION description list is empty ()      -> Pattern 4
│   ├─ a header entity is missing or out of order        -> Pattern 4
│   └─ FILE_SCHEMA missing, wrong, or lowercase id        -> Pattern 5
└─ code or query expects an IfcFileDescription entity
    -> the header is STEP, not IFC                        -> Pattern 6

Is this a stage-1 or a later-stage error

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)

Mojibake is text that parsed without a syntax error but displays as garbage : Cafe written correctly but shown as Café, or a pound sign shown as £. The cause is a mismatch : the file was WRITTEN with one character set and READ with another, typically UTF-8 bytes interpreted as Latin-1.

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-syntax-express : EXPRESS types, LIST/SET cardinality notation.
• 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.