Reported issues for MagicTeX

Pod holds 16 of 32 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to MagicTeX.

Most discussed

System-TeX backend: a TeX installed after startup is invisible, and when latexmk cannot run we report the wrong reason

Found by testing a real IEEEtran paper on Windows against the published 0.1.9, rather than by review. Three defects, and they chain: the first makes the second reachable, and the third is why a user walks into them at all.

1. A TeX installed after the server started is invisible, forever

src/engine/systemTex.ts:

let cached: 'latexmk' | null | undefined;
export async function hasSystemTex(): Promise<boolean> {
  if (cached !== undefined) return cached !== null;   // one null, always

[Read the thread](https://github.com/ZoeLinUTS/MagicTeX-mcp/issues/89) · 2026-07-27 · closed · 2 comments

### Ctrl+S sometimes reports a compile success that did not happen, and the preview can stay on the previous version

Reported from real use on a 15-page IEEE paper, system backend:

> 有时候不知道为什么需要刷新页面才能看到最新更新,CTRL S 有时候报假的编译成功
>
> (sometimes the page has to be reloaded before the update shows; Ctrl+S
> sometimes reports a compile success that did not happen)

Both are intermittent, so what follows separates what is verified from what is
not. A tool for writing papers reporting a success that did not happen is the
worst failure it has, so this is filed even though the mechanism is not yet
pinned.

## Verified: w

[Read the thread](https://github.com/ZoeLinUTS/MagicTeX-mcp/issues/98) · 2026-07-27 · closed · 1 comment

### MAGICTEX_ASSETS_DIR with forward slashes 403s every engine asset on Windows, and the same guard's containment check has no separator boundary

Found while verifying the 0.1.9 artifact from npm — not introduced by it, and not
caught by any test because every test and smoke lets the asset directory be
discovered rather than set.

`serveFrom` in `src/preview/previewServer.ts`:

```ts
const filePath = normalize(join(root, rel));
if (!filePath.startsWith(root)) { res.writeHead(403).end('forbidden'); return; }

Two defects in those two lines.

1. `MAGICTEX_ASSETS_DIR` with forward slashes 403s every engine asset

join/normalize re

Read the thread · 2026-07-26 · closed · 1 comment

Harden the local preview server (details held until 0.1.9 is published)

Found by /code-review ultra over the whole of src/, ui/src/ and bin/.

Details are held back until 0.1.9 is published — 0.1.8 is the version on npm and does not have these fixes. A full write-up will be added to this issue after the release. What follows is enough to review the change without being a recipe.

The shape of it

The preview server binds 127.0.0.1. That keeps other machines out, and says nothing about the user's own browser: localhost is reachable from every origin

Read the thread · 2026-07-26 · closed · 1 comment

Docs are out of step with the code: a startup check that doesn't exist, a wrong download size, and translations missing half their sections

An audit of the docs against the code turned up three gaps. The first is a promise the code never kept; the other two are wrong or missing facts a reader would act on.

1. The README claims a startup check that does not exist

Node 20.19+ (the floor chokidar and playwright actually need; the server checks at startup and says so)

$ grep -rn "process.version" src/
$

Nothing reads it. engines in package.json only makes npm warn, and the documented install lin

Read the thread · 2026-07-26 · closed · 1 comment

Two servers compiling one project corrupt the build, and it never recovers on its own

Two MagicTeX servers compiling the same project corrupt each other's build, and the failure that comes out of it points nowhere near the cause.

Reproduced by accident and in full: a second process ran render_preview against a project a running workspace was already compiling. Both write .latex-preview/build/ and, with shell-escape on, the same Inkscape output under svg-inkscape/. One of them read a half-written intermediate:

xdvipdfmx:warning: >> Reading special command stopped aroun

[Read the thread](https://github.com/ZoeLinUTS/MagicTeX-mcp/issues/95) · 2026-07-27 · open · 0 comments

### The new system-TeX guidance claims a local run that never happened, and blames it for the wrong failure

The guidance added in #90 asserts two things it has not measured — the same
mistake #89 was filed about, made one level down inside its own fix. Both are in
`main` now, and 0.1.10's version bump is already there too, so they would ship.

Found by running the merged code against a real IEEEtran paper rather than by
reading it.

**It reports a run that never happened.** With `backend: "wasm"` forced, nothing
is invoked locally, but the message says:

> Your local TeX ran and did not get through th

[Read the thread](https://github.com/ZoeLinUTS/MagicTeX-mcp/issues/91) · 2026-07-27 · closed · 0 comments

### Releasing is four steps kept only as habit — 0.1.9 shipped with two of them missed

Releasing this project takes four steps, and they exist only as habit. 0.1.9
shipped with two of them missed, by me, and nothing anywhere would have caught it:

| step | 0.1.8 | 0.1.9 |
| --- | --- | --- |
| `RELEASE-x.y.z.md` committed | ✅ | ❌ |
| `npm publish` | ✅ | ✅ |
| GitHub release (body = that file) | ✅ | ✅ |
| `mcp-publisher publish` (server.json) | ✅ | ❌ |

The MCP registry still lists **0.1.8** as latest:

0.1.2 0.1.3 0.1.4 0.1.5 0.1.6 0.1.7 0.1.8 <-- isLatest


so anyone

[Read the thread](https://github.com/ZoeLinUTS/MagicTeX-mcp/issues/87) · 2026-07-27 · closed · 0 comments

## Most recent

### First-run asset download breaks on Windows when the user's home path contains a space

Found by the full-codebase review before 0.1.9. This one breaks the **first
compile on a new machine**, for a large share of Windows users.

`src/engine/assets.ts` launches the one-time 480 MB asset download like this:

```ts
spawn('npx', ['texlyre-busytex', 'download-assets', dest], {
  shell: process.platform === 'win32', // npx.cmd on Windows
});

With shell: true, Node does not hand the child an argv. It joins the arguments with spaces into a single command line and passes that to the

Read the thread · 2026-07-26 · closed · 0 comments

History is keyed by the project path, so a reused path inherits another project's checkpoints — and Restore writes them over your files

Found by the full-codebase review before 0.1.9. Same area as #77, different mechanism, and the one that can overwrite a paper you are actually working on.

historyRepo() picks the shadow repo's directory by hashing the project's resolved path:

const hash = createHash('sha256').update(key).digest('hex').slice(0, 16);
return join(cacheRoot(), 'history', hash);

So the history belongs to the path, not to the project. Four consequences, all silent:

**Rename the folder and the timel

Read the thread · 2026-07-26 · closed · 0 comments

The legacy /viewer never learns its server stopped — and no smoke has ever loaded it

The stale-window warning from #57 was added to the React workspace at /app. The legacy /viewer never got it — and /viewer is what render_preview opens whenever ui/dist/index.html is missing:

const hasWorkspace = existsSync(join(PKG_ROOT, 'ui', 'dist', 'index.html'));
…
const workspaceUrl = hasWorkspace ? `${preview.url}/app` : preview.viewerUrl;

which is a fresh clone before npm run build:ui — the from-source setup the README documents — or any publish where the built wor

Read the thread · 2026-07-26 · closed · 0 comments

Only the toolbar was told the window is dead — the editor keeps writing to a closed port

The dead-window signal from #57 was threaded to the toolbar and nowhere else, so every other surface keeps writing to a closed port. Found by /code-review ultra.

The one that costs the user their text

SourcePanel is rendered with no status, so after the server stops:

the 30-second autosave keeps PUTting to /api/file,
the Live-mode debounce does the same on every keystroke pause,
and both fail into a bare catch { setSaveState('error') }.

Measured in the browser, on the sh

Read the thread · 2026-07-26 · closed · 0 comments

The shutdown added in #57 cannot finish in time, and can rebuild what it tore down

The shutdown added in #57 does not complete inside the window it has, and can recreate the very things it just tore down. Found by /code-review ultra; the first two are measured, not reasoned.

The budget

StdioClientTransport.close() (@modelcontextprotocol/sdk client/stdio.js:147-166) disconnects like this:

stdin.end()  →  2s  →  SIGTERM  →  2s  →  SIGKILL

Everything below has to finish inside that, or the process is killed still holding Chromium and the port.

1. close() wa

Read the thread · 2026-07-26 · closed · 0 comments

The Node version check added in #58 is dead code, and #58's claim that no check existed is false

Follow-up to #59, correcting it.

#59 was wrong, and so was the commit that closed it

#59 said "the README claims a startup check that does not exist" and showed:

$ grep -rn "process.version" src/
$

That search was the mistake. bin/cli.mjs — the file package.json maps magictex-mcp to — has had the check since before any of this:

const MIN_MAJOR = 20;
const MIN_MINOR = 19;
const [major, minor] = process.versions.node.split('.').map(Number);
if (major < MIN_MAJOR 

[Read the thread](https://github.com/ZoeLinUTS/MagicTeX-mcp/issues/60) · 2026-07-26 · closed · 0 comments

### Nothing is cleaned up on exit: leaked servers keep compiling, and stale tabs look alive

A user reported `render failed` from a workspace tab while a *different*, healthy
instance was compiling their paper fine on another port. Both statements were
true. The tab was pointed at a server that no longer existed, and nothing on
screen said so.

This is an audit of what the process actually cleans up when it goes away. The
answer is nothing.

## Findings

**1. Neither cleanup function is called by anything.**

src/engine/browserHost.ts:136 export async function shutdownEngine() src

Read the thread · 2026-07-26 · closed · 0 comments

\includesvg fails on both backends, and the error explains neither

A paper with \includesvg cannot compile on either backend, and the error explains none of it.

Real log from a user's paper:

wasn't possible to launch the Inkscape export
(svg)                for `fig/Fed_CMA architecture diagram2.svg' on input line 113.

! Package svg Error: File `Fed_CMA architecture diagram2_svg-tex.pdf' is missing.

Did you run the export with Inkscape? There's no file
`./svg-inkscape/Fed_CMA architecture diagram2_svg-tex.pdf'

The svg package doesn't embed SVGs

Read the thread · 2026-07-26 · closed · 0 comments

The remaining reports are on the project's issue tracker.

Reported issues for MagicTeX

Most discussed

System-TeX backend: a TeX installed after startup is invisible, and when latexmk cannot run we report the wrong reason

1. A TeX installed after the server started is invisible, forever

1. MAGICTEX_ASSETS_DIR with forward slashes 403s every engine asset

Harden the local preview server (details held until 0.1.9 is published)

The shape of it

Docs are out of step with the code: a startup check that doesn't exist, a wrong download size, and translations missing half their sections

1. The README claims a startup check that does not exist

Two servers compiling one project corrupt the build, and it never recovers on its own

History is keyed by the project path, so a reused path inherits another project's checkpoints — and Restore writes them over your files

The legacy /viewer never learns its server stopped — and no smoke has ever loaded it

Only the toolbar was told the window is dead — the editor keeps writing to a closed port

The one that costs the user their text

The shutdown added in #57 cannot finish in time, and can rebuild what it tore down

The budget

1. close() wa

The Node version check added in #58 is dead code, and #58's claim that no check existed is false

#59 was wrong, and so was the commit that closed it

\includesvg fails on both backends, and the error explains neither

1. `MAGICTEX_ASSETS_DIR` with forward slashes 403s every engine asset