{"record":{"id":"431a79a2d790dae5","repo":"iOfficeAI/OfficeCLI","slug":"failed-to-parse-formula-ex-message-see-https","errorCode":null,"errorMessage":"Failed to parse formula: {ex.Message} See https://katex.org/docs/supported.html for supported syntax.","messagePattern":"Failed to parse formula: (.+?) See https://katex\\.org/docs/supported\\.html for supported syntax\\.","errorType":"exception","errorClass":"FormulaParseException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/Formula/FormulaParser.cs","lineNumber":120,"sourceCode":"            // If such a wrapper lands inside an <m:e>/<m:num>/<m:den>/… without\n            // being unwrapped, the result is a nested <m:oMath>, which is invalid\n            // OMML — Word refuses to open the file (\"file may be corrupt\") even\n            // though the SDK validator tolerates it. Flatten any non-root oMath.\n            FlattenNestedOfficeMath(root);\n            return root;\n        }\n        catch (FormulaParseException)\n        {\n            // A FormulaParseException thrown from inside the parser (e.g. the\n            // depth guard at ParseGroup) already carries the KaTeX hint.\n            // Re-wrapping it here would append the hint a second time, so let\n            // it propagate unchanged. Only foreign exceptions get the wrap +\n            // hint below.\n            throw;\n        }\n        catch (Exception ex)\n        {\n            throw new FormulaParseException(\n                $\"Failed to parse formula: {ex.Message} {KatexDocsHint}\", ex);\n        }\n        finally\n        {\n            _unrecognized = prevUnrecognized;\n        }\n    }\n\n    /// <summary>\n    /// Lenient parse for the handler add/set paths. Behaves exactly like\n    /// <see cref=\"Parse(string, ICollection{string}?)\"/> but, instead of\n    /// throwing a <see cref=\"FormulaParseException\"/> (which would propagate to\n    /// exit 1 and, in a batch, fail the WHOLE batch), it RECORDS the failure on\n    /// the same diagnostics channel used for unrecognized commands and returns a\n    /// minimal valid placeholder <m:oMath> carrying the literal source text.\n    /// R3-fuzz-1: this makes a too-deep / unparseable equation consistent with\n    /// the unrecognized-command model — a visible warning + exit 2 + a graceful\n    /// lenient write — rather than an exit-1 hard failure that sinks the batch.","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/Formula/FormulaParser.cs#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"Unsupported KaTeX construct; malformed LaTeX that breaks an internal assumption; a token the lexer cannot classify leading to an unrelated exception type.","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)."],"exampleFix":"// before\nparser.Parse(@\"\\unsupportedCmd{x}\");\n// after\nparser.Parse(@\"\\textbf{x}\"); // use a supported KaTeX command","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { parser.Parse(formula); }\ncatch (FormulaParseException ex)\n{ /* show ex.Message incl. KaTeX docs link to the user */ }","preventionTips":["Restrict the editor/UI to the KaTeX-supported construct set.","Keep a whitelist of allowed LaTeX commands if accepting user formulas."],"tags":["formula","katex","latex","parsing"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}