Troubleshoot FontForge Feature File Compiling Errors

Compiling OpenType feature files (.fea) in FontForge can frequently trigger cryptic syntax or parsing errors due to strict specification requirements, missing glyph mappings, or engine-specific limitations. This guide outlines the essential troubleshooting workflow to identify error locations, interpret FontForge's error logs, fix common OpenType syntax mistakes, and resolve compatibility issues between standard Adobe FEA syntax and FontForge's internal parser.

Read the Error Output Carefully

When FontForge fails to parse a feature file, it outputs an error message either in the pop-up warning dialog or via the standard output/terminal if running via command line.

  • Look for the specific line number reported. FontForge usually specifies the exact line and character offset where parsing broke down.
  • If FontForge crashes or gives a generic "Parse failed" error without a line number, run FontForge from your system terminal (fontforge yourfont.sfd) to view raw standard error outputs.

Check for Missing Glyph Names

The most frequent cause of compile failure is referencing glyph names in the feature file that do not exist in the font database.

  • Name Mismatches: Ensure that all names used in substitution (sub) or positioning (pos) rules precisely match the PostScript glyph names in your font. Remember that glyph names are case-sensitive (e.g., a.sc is distinct from A.sc).
  • Unencoded Glyphs: If your glyph lacks a Unicode codepoint, confirm it still has a valid PostScript name assigned in the Glyph Info panel (Element > Glyph Info).

Validate OpenType Syntax Rules

FontForge's parser expects strict adherence to the Adobe OpenType Feature File specification. Ensure basic syntax requirements are satisfied:

  • Missing Semicolons: Every statement, rule, and class assignment must terminate with a semicolon (;). A missing semicolon on line 10 often causes the parser to throw an error on line 11 or 12.
  • Mismatched Braces and Brackets: Ensure all glyph classes ([...]) and lookup blocks ({...}) are properly closed.
  • Explicit Lookup Blocks: If you reference a lookup within a feature block, verify that the lookup definition matches the lookup type expected by the feature.

Check Glyph Class Symmetry in Substitutions

When using glyph classes in contextual or ligature substitutions, both sides of the rule must match in dimension:

  • Equal Class Lengths: If writing a rule such as sub [a b c] by [A.sc B.sc C.sc];, both classes must contain the exact same number of glyphs.
  • Valid Targets: In many-to-one substitutions (ligatures), ensure the target is a single glyph, not a class, unless intentional contextual rules are properly flagged.

Watch for FontForge Parser Limitations

FontForge's built-in parser does not support every modern feature of the Adobe Font Development Kit for OpenType (AFDKO) specification:

  • Advanced Statements: Modern AFDKO syntax features—such as inline variable declarations, certain chaining contextual rules, or complex Mark-to-Mark anchoring—may fail in older FontForge builds.
  • Alternative Import: If a feature file compiles cleanly using AFDKO's makeotf tool but fails in FontForge, strip optional statements like languagesystem redeclarations or simplify complex nested lookups into standalone lookup blocks.

Use the Isolation (Binary Search) Method

If the error message points to a misleading line number:

  1. Comment out large sections of the feature file using # at the start of each line.
  2. Re-import the file into FontForge (File > Merge Feature Info...).
  3. Uncomment blocks sequentially (e.g., feature by feature: kern, then liga, then calt) until the error reappears.
  4. Once the problematic feature is isolated, narrow it down to the exact line causing the parser exception.