[GH-ISSUE #21612] bug: LaTeX Rendering Fails for API-Connected Models Using Standard Delimiter Conventions #19538

New Issue

GiteaMirror · 2026-04-20T02:00:45-05:00

GiteaMirror commented

2026-04-20 02:00:45 -05:00

Originally created by @BrutchsamaJeanLouis on GitHub (Feb 19, 2026).
Original GitHub issue: https://github.com/open-webui/open-webui/issues/21612

Check Existing Issues

I have searched for any existing and/or related issues.
I have searched for any existing and/or related discussions.
I have also searched in the CLOSED issues AND CLOSED discussions and found no related items (your issue might already be addressed on the development branch!).
I am using the latest version of Open WebUI.

Installation Method

Docker

Open WebUI Version

v0.8.3

Ollama Version (if applicable)

Latest (issue primarily affects API-connected models, not Ollama-specific)

Operating System

Reproducible across Windows, macOS, Linux

Browser (if applicable)

Reproducible across Chrome, Firefox, Brave (latest stable versions)

Confirmation

I have read and followed all instructions in README.md.
I am using the latest version of both Open WebUI and Ollama.
I have included the browser console logs.
I have included the Docker container logs.
I have provided every relevant configuration, setting, and environment variable used in my setup.
I have clearly listed every relevant configuration, custom setting, environment variable, and command-line option that influences my setup (such as Docker Compose overrides, .env values, browser settings, authentication configurations, etc).
I have documented step-by-step reproduction instructions that are precise, sequential, and leave nothing to interpretation. My steps:
Start with the initial platform/version/OS and dependencies used,
Specify exact install/launch/configure commands,
List URLs visited, user input (incl. example values/emails/passwords if needed),
Describe all options and toggles enabled or changed,
Include any files or environmental changes,
Identify the expected and actual result at each stage,
Ensure any reasonably skilled user can follow and hit the same issue.

Expected Behavior

All standard LaTeX delimiter formats should render correctly and consistently:

Input Format	Type	Expected Rendering
$x^2$	Inline math	Rendered inline as x²
`$$\sum_{i=1}^{n} i$$`	Display math	Rendered as centered block equation
`$x^2$`	Inline math (alt)	Rendered inline as x²
`\[\sum_{i=1}^{n} i\]`	Display math (alt)	Rendered as centered block equation
$O(n \log n)$	Inline within prose	Rendered inline without breaking paragraph flow

Mixed content like the following should render seamlessly:

The Handshaking Lemma states that $\sum_{v \in V} \deg(v) = 2|E|$.
If all 5 vertices have degree 3, then:

$$\sum_{v \in V} \deg(v) = 15$$

which is odd — contradicting the lemma. QED.

Expected result: Inline expression renders within the sentence. Display expression renders as a centered block. Surrounding markdown (bold, headers, paragraphs) is unaffected.

Actual Behavior

Single $ inline math fails to render. Models default to $...$ for inline math (standard LaTeX convention). OpenWebUI's KaTeX configuration historically requires $$...$$ even for inline expressions, or silently fails.
Multi-line display math with \[...\] breaks. When \[ and \] appear on separate lines (which models frequently produce for readability), rendering fails entirely and raw LaTeX syntax is shown to the user.
Inconsistent rendering within a single response. Some expressions render while others in the same message do not. There is no predictable pattern — identical delimiter formats can succeed or fail depending on surrounding markdown context (e.g., expressions adjacent to bold text, inside lists, or following headers).
Streaming rendering artifacts. During streamed responses, partially received LaTeX expressions can trigger KaTeX parse errors that persist even after the full expression is received, requiring a page refresh.
Model instruction workarounds are unreliable. Adding system prompt instructions like "always use $$ delimiters" does not reliably change model output. Models inconsistently follow delimiter format instructions — sometimes using \\, \\\, or \\\\ for the same escape sequence, and reverting to single $ for inline math regardless of instructions.

Root Cause Analysis:

KaTeX's auto-render configuration in OpenWebUI does not include single $ as a delimiter by default. This is a configuration choice, not a KaTeX limitation.
Markdown-LaTeX parser conflicts: The markdown renderer processes $ characters before KaTeX can identify them as math delimiters.
No normalization layer exists between model output and rendering. Native interfaces (claude.ai, ChatGPT) include output post-processing that normalizes delimiter formats before rendering.

Steps to Reproduce

Install Open WebUI v0.8.3 via Docker (standard docker-compose setup, no custom modifications).
Connect any frontier model via API (Claude via Anthropic API, GPT-4 via OpenAI-compatible endpoint, etc.).
Ask: "Explain the Handshaking Lemma with formal notation inline."
Observe: inline $...$ expressions appear as raw text instead of rendered math.
Ask: "Now write the formal proof using display equations."
Observe: some $$...$$ blocks render, others do not, especially when interleaved with markdown formatting.

Contrast: The same model producing the same tokens renders all math correctly in its native interface (claude.ai, chat.openai.com), because those platforms control both generation and rendering pipelines.

Note: This issue has been reported across versions 0.3.x, 0.4.x, 0.5.x, and 0.8.x. See related issues: #2365, #2615, #3581, #8299, #8437, and Discussion #18508.

Logs & Screenshots

This is a rendering/configuration issue rather than a crash — no specific error logs are produced. The failure mode is silent: LaTeX delimiters are passed through as raw text rather than triggering KaTeX rendering. In the browser console, KaTeX parse errors may occasionally appear during streaming when partial LaTeX expressions are received.

Additional Information

Proposed Solutions (in order of implementation effort)

1. Enable single `$` delimiters in KaTeX configuration

Add {left: "$", right: "$", display: false} to the KaTeX auto-render delimiter configuration. This is a one-line change that resolves the most common failure mode.

2. Add a LaTeX normalization pipeline stage

Implement a pre-render pass that normalizes model output before it reaches the markdown parser:

Convert $...$ → $...$
Convert \[...\] → $$...$$
Normalize backslash escaping inconsistencies
Protect LaTeX delimiters from markdown parser interference

This is similar to what the community LaTeX Display Optimization filter does, but should be built into the core rendering pipeline rather than requiring user-installed functions.

3. Configurable math renderer (KaTeX vs MathJax)

As raised in Discussion #18508 — provide an option to switch to MathJax, which handles delimiter ambiguity more gracefully and supports a wider range of LaTeX commands. This could be a user-facing setting in Settings > Interface.

4. Render-time delimiter detection

Implement intelligent delimiter detection that identifies probable LaTeX content even when delimiters are non-standard or ambiguous, similar to how VS Code's markdown preview handles mixed math content.

Impact

This issue disproportionately affects:

Academic users working through mathematical content with LLMs
API users connecting frontier models where the native interface handles math rendering correctly
Technical educators using LLMs for STEM explanation where notation is interleaved with narrative

The current state forces users to choose between: (a) degraded rendering quality, (b) system prompt workarounds that unreliably constrain model output, or (c) installing community filter functions that add maintenance overhead and don't fully resolve the issue.

#2365 — Root cause analysis of single vs double dollar delimiter
#2615 — Feature request for configurable LaTeX delimiters
#3581 — LaTeX rendering failures across languages
#8299 — Random rendering breakage
#8437 — Raw LaTeX syntax visible instead of rendered
Discussion #18508 — Request to switch from KaTeX to MathJax

Models tested: Claude 3.5/4 via Anthropic API, GPT-4 via OpenAI-compatible endpoint, Llama 3 via Ollama

Originally created by @BrutchsamaJeanLouis on GitHub (Feb 19, 2026). Original GitHub issue: https://github.com/open-webui/open-webui/issues/21612 ### Check Existing Issues - [x] I have searched for any existing and/or related issues. - [x] I have searched for any existing and/or related discussions. - [x] I have also searched in the CLOSED issues AND CLOSED discussions and found no related items (your issue might already be addressed on the development branch!). - [x] I am using the latest version of Open WebUI. ### Installation Method Docker ### Open WebUI Version v0.8.3 ### Ollama Version (if applicable) Latest (issue primarily affects API-connected models, not Ollama-specific) ### Operating System Reproducible across Windows, macOS, Linux ### Browser (if applicable) Reproducible across Chrome, Firefox, Brave (latest stable versions) ### Confirmation - [x] I have read and followed all instructions in `README.md`. - [x] I am using the latest version of **both** Open WebUI and Ollama. - [x] I have included the browser console logs. - [x] I have included the Docker container logs. - [x] I have **provided every relevant configuration, setting, and environment variable used in my setup.** - [x] I have clearly **listed every relevant configuration, custom setting, environment variable, and command-line option that influences my setup** (such as Docker Compose overrides, .env values, browser settings, authentication configurations, etc). - [x] I have documented **step-by-step reproduction instructions that are precise, sequential, and leave nothing to interpretation**. My steps: - Start with the initial platform/version/OS and dependencies used, - Specify exact install/launch/configure commands, - List URLs visited, user input (incl. example values/emails/passwords if needed), - Describe all options and toggles enabled or changed, - Include any files or environmental changes, - Identify the expected and actual result at each stage, - Ensure any reasonably skilled user can follow and hit the same issue. ### Expected Behavior All standard LaTeX delimiter formats should render correctly and consistently: | Input Format | Type | Expected Rendering | |---|---|---| | `$x^2$` | Inline math | Rendered inline as x² | | `$$\sum_{i=1}^{n} i$$` | Display math | Rendered as centered block equation | | `$x^2$` | Inline math (alt) | Rendered inline as x² | | `\[\sum_{i=1}^{n} i\]` | Display math (alt) | Rendered as centered block equation | | `$O(n \log n)$` | Inline within prose | Rendered inline without breaking paragraph flow | Mixed content like the following should render seamlessly: ``` The Handshaking Lemma states that $\sum_{v \in V} \deg(v) = 2|E|$. If all 5 vertices have degree 3, then: $$\sum_{v \in V} \deg(v) = 15$$ which is odd — contradicting the lemma. QED. ``` **Expected result:** Inline expression renders within the sentence. Display expression renders as a centered block. Surrounding markdown (bold, headers, paragraphs) is unaffected. ### Actual Behavior 1. **Single `$` inline math fails to render.** Models default to `$...$` for inline math (standard LaTeX convention). OpenWebUI's KaTeX configuration historically requires `$$...$$` even for inline expressions, or silently fails. 2. **Multi-line display math with `\[...\]` breaks.** When `\[` and `\]` appear on separate lines (which models frequently produce for readability), rendering fails entirely and raw LaTeX syntax is shown to the user. 3. **Inconsistent rendering within a single response.** Some expressions render while others in the same message do not. There is no predictable pattern — identical delimiter formats can succeed or fail depending on surrounding markdown context (e.g., expressions adjacent to bold text, inside lists, or following headers). 4. **Streaming rendering artifacts.** During streamed responses, partially received LaTeX expressions can trigger KaTeX parse errors that persist even after the full expression is received, requiring a page refresh. 5. **Model instruction workarounds are unreliable.** Adding system prompt instructions like "always use $$ delimiters" does not reliably change model output. Models inconsistently follow delimiter format instructions — sometimes using `\\`, `\\\`, or `\\\\` for the same escape sequence, and reverting to single `$` for inline math regardless of instructions. **Root Cause Analysis:** - **KaTeX's auto-render configuration** in OpenWebUI does not include single `$` as a delimiter by default. This is a configuration choice, not a KaTeX limitation. - **Markdown-LaTeX parser conflicts:** The markdown renderer processes `$` characters before KaTeX can identify them as math delimiters. - **No normalization layer** exists between model output and rendering. Native interfaces (claude.ai, ChatGPT) include output post-processing that normalizes delimiter formats before rendering. ### Steps to Reproduce 1. Install Open WebUI v0.8.3 via Docker (standard docker-compose setup, no custom modifications). 2. Connect any frontier model via API (Claude via Anthropic API, GPT-4 via OpenAI-compatible endpoint, etc.). 3. Ask: "Explain the Handshaking Lemma with formal notation inline." 4. Observe: inline `$...$` expressions appear as raw text instead of rendered math. 5. Ask: "Now write the formal proof using display equations." 6. Observe: some `$$...$$` blocks render, others do not, especially when interleaved with markdown formatting. **Contrast:** The same model producing the same tokens renders all math correctly in its native interface (claude.ai, chat.openai.com), because those platforms control both generation and rendering pipelines. **Note:** This issue has been reported across versions 0.3.x, 0.4.x, 0.5.x, and 0.8.x. See related issues: #2365, #2615, #3581, #8299, #8437, and Discussion #18508. ### Logs & Screenshots This is a rendering/configuration issue rather than a crash — no specific error logs are produced. The failure mode is silent: LaTeX delimiters are passed through as raw text rather than triggering KaTeX rendering. In the browser console, KaTeX parse errors may occasionally appear during streaming when partial LaTeX expressions are received. ### Additional Information ## Proposed Solutions (in order of implementation effort) ### 1. Enable single `$` delimiters in KaTeX configuration Add `{left: "$", right: "$", display: false}` to the KaTeX auto-render delimiter configuration. This is a one-line change that resolves the most common failure mode. ### 2. Add a LaTeX normalization pipeline stage Implement a pre-render pass that normalizes model output before it reaches the markdown parser: - Convert `$...$` → `$...$` - Convert `\[...\]` → `$$...$$` - Normalize backslash escaping inconsistencies - Protect LaTeX delimiters from markdown parser interference This is similar to what the community LaTeX Display Optimization filter does, but should be built into the core rendering pipeline rather than requiring user-installed functions. ### 3. Configurable math renderer (KaTeX vs MathJax) As raised in Discussion #18508 — provide an option to switch to MathJax, which handles delimiter ambiguity more gracefully and supports a wider range of LaTeX commands. This could be a user-facing setting in Settings > Interface. ### 4. Render-time delimiter detection Implement intelligent delimiter detection that identifies probable LaTeX content even when delimiters are non-standard or ambiguous, similar to how VS Code's markdown preview handles mixed math content. ## Impact This issue disproportionately affects: - **Academic users** working through mathematical content with LLMs - **API users** connecting frontier models where the native interface handles math rendering correctly - **Technical educators** using LLMs for STEM explanation where notation is interleaved with narrative The current state forces users to choose between: (a) degraded rendering quality, (b) system prompt workarounds that unreliably constrain model output, or (c) installing community filter functions that add maintenance overhead and don't fully resolve the issue. ## Related Issues and Discussions - #2365 — Root cause analysis of single vs double dollar delimiter - #2615 — Feature request for configurable LaTeX delimiters - #3581 — LaTeX rendering failures across languages - #8299 — Random rendering breakage - #8437 — Raw LaTeX syntax visible instead of rendered - Discussion #18508 — Request to switch from KaTeX to MathJax **Models tested:** Claude 3.5/4 via Anthropic API, GPT-4 via OpenAI-compatible endpoint, Llama 3 via Ollama

GiteaMirror added the bug label 2026-04-20 02:00:45 -05:00

GiteaMirror closed this issue

2026-04-20 02:00:46 -05:00

GiteaMirror commented

2026-04-20 02:00:47 -05:00

@pr-validator-bot commented on GitHub (Feb 19, 2026):

⚠️ Missing Issue Title Prefix

@BrutchsamaJeanLouis, your issue title is missing a prefix (e.g., bug:, feat:, docs:).

Please update your issue title to include one of the following prefixes:

bug: Bug report or error you've encountered
feat: Feature request or enhancement suggestion
docs: Documentation issue or improvement request
question: Question about usage or functionality
help: Request for help or support

Example: bug: Login fails when using special characters in password

@pr-validator-bot commented on GitHub (Feb 19, 2026): # ⚠️ Missing Issue Title Prefix @BrutchsamaJeanLouis, your issue title is missing a prefix (e.g., `bug:`, `feat:`, `docs:`). Please update your issue title to include one of the following prefixes: - **bug**: Bug report or error you've encountered - **feat**: Feature request or enhancement suggestion - **docs**: Documentation issue or improvement request - **question**: Question about usage or functionality - **help**: Request for help or support Example: `bug: Login fails when using special characters in password`

GiteaMirror commented

2026-04-20 02:00:48 -05:00

@tjbck commented on GitHub (Feb 20, 2026):

Intended. If we blindly enable this will break the actual text rendering. Open to discussion.

@tjbck commented on GitHub (Feb 20, 2026): Intended. If we blindly enable this will break the actual text rendering. Open to discussion.

GiteaMirror referenced this issue

2026-04-25 08:27:01 -05:00

[GH-ISSUE #19538] issue: Batch file addition issue with Knowledge API (api/v1/knowledge/{id}/files/batch/add) #34447

GiteaMirror referenced this issue

2026-05-05 21:09:54 -05:00

[GH-ISSUE #19538] issue: Batch file addition issue with Knowledge API (api/v1/knowledge/{id}/files/batch/add) #57584

Sign in to join this conversation.