# Ifc Errors Encoding Issues > 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 - Skill: `impertio-studio/ifc-errors-encoding-issues` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add impertio-studio/ifc-errors-encoding-issues` - Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/ifc-errors-encoding-issues/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: Impertio-Studio (https://skillmd.com/u/impertio-studio) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/impertio-studio/ifc-errors-encoding-issues --- # 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`.