iOfficeAI/OfficeCLI · error · FormulaParseException

Failed to parse formula: {ex.Message} See https://katex.org/

Error message

Failed to parse formula: {ex.Message} See https://katex.org/docs/supported.html for supported syntax.

What it means

Thrown by the formula parser when an unexpected (non-FormulaParseException) exception occurs during parsing; it wraps the original exception and appends a link to the KaTeX supported-syntax docs. FormulaParseExceptions raised inside the parser are allowed to propagate unchanged to avoid double-appending the hint.

Source

Thrown at src/officecli/Core/Formula/FormulaParser.cs:120

            // If such a wrapper lands inside an <m:e>/<m:num>/<m:den>/… without
            // being unwrapped, the result is a nested <m:oMath>, which is invalid
            // OMML — Word refuses to open the file ("file may be corrupt") even
            // though the SDK validator tolerates it. Flatten any non-root oMath.
            FlattenNestedOfficeMath(root);
            return root;
        }
        catch (FormulaParseException)
        {
            // A FormulaParseException thrown from inside the parser (e.g. the
            // depth guard at ParseGroup) already carries the KaTeX hint.
            // Re-wrapping it here would append the hint a second time, so let
            // it propagate unchanged. Only foreign exceptions get the wrap +
            // hint below.
            throw;
        }
        catch (Exception ex)
        {
            throw new FormulaParseException(
                $"Failed to parse formula: {ex.Message} {KatexDocsHint}", ex);
        }
        finally
        {
            _unrecognized = prevUnrecognized;
        }
    }

    /// <summary>
    /// Lenient parse for the handler add/set paths. Behaves exactly like
    /// <see cref="Parse(string, ICollection{string}?)"/> but, instead of
    /// throwing a <see cref="FormulaParseException"/> (which would propagate to
    /// exit 1 and, in a batch, fail the WHOLE batch), it RECORDS the failure on
    /// the same diagnostics channel used for unrecognized commands and returns a
    /// minimal valid placeholder <m:oMath> carrying the literal source text.
    /// R3-fuzz-1: this makes a too-deep / unparseable equation consistent with
    /// the unrecognized-command model — a visible warning + exit 2 + a graceful
    /// lenient write — rather than an exit-1 hard failure that sinks the batch.

View on GitHub (pinned to 1ced45e900)

Solutions

Consult the linked KaTeX docs and adjust the formula to supported syntax.
Simplify the formula to isolate the unsupported construct.
If the underlying exception is unexpected, report it with the original message (preserved as InnerException).

Example fix

// before
parser.Parse(@"\unsupportedCmd{x}");
// after
parser.Parse(@"\textbf{x}"); // use a supported KaTeX command

Defensive patterns

Strategy: try-catch

Try / catch

try { parser.Parse(formula); }
catch (FormulaParseException ex)
{ /* show ex.Message incl. KaTeX docs link to the user */ }

Prevention

Restrict the editor/UI to the KaTeX-supported construct set.
Keep a whitelist of allowed LaTeX commands if accepting user formulas.

When it happens

Trigger: Calling the formula parse API (Parse) with a LaTeX/KaTeX-style formula string that triggers a foreign exception during tokenizing/parsing — anything other than the parser's own structured FormulaParseException.

Common situations: Unsupported KaTeX construct; malformed LaTeX that breaks an internal assumption; a token the lexer cannot classify leading to an unrelated exception type.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/431a79a2d790dae5. Report an issue: GitHub.