wolfram-headless

wolfram-headless — reliable headless Wolfram in Claude Code

Hard-won rules for running wolframscript from Claude Code's Bash tool. Two findings dominate: (1) "The product exited because of a license error" is almost never a license problem — it is a kernel crash (usually a memory spike) mis-reported; and (2) literal Greek Unicode in .wls files silently corrupts symbols under wolframscript. Both cost real time; this skill encodes the fix.

RULE 1 — ASCII escapes in .wls, NEVER literal Greek (silent-corruption bug)

wolframscript reads .wls files under a non-UTF-8 encoding, so a literal ω (U+03C9) becomes a different, dead symbol (mojibake ω), with no error. ω3 =!= \[Omega]3; any ===/pattern test against the real symbol silently fails and results are wrong. Verified: a function keyed on the real \[Omega]3 falls through / returns garbage when fed the literal-ω symbol.

• In every .wls, write \[Omega] \[Alpha] \[CapitalLambda] \[CapitalDelta] \[Pi] \[Epsilon] \[Tau] \[Mu] \[Xi], never the literal characters. Pi, I, Infinity, and ASCII names (Delta, Esq, tau) are fine.
• The notebook/desktop kernel (Mathematica FE / Wolfbook in VS Code) handles literal Greek fine — this is headless-.wls-only. So copying notebook code into a .wls introduces the bug.
• Quick converter (run before any heavy job): replace the Greek chars with their \[...] escapes. A one-liner is in scripts/greek2esc.py next to this skill.
• Audit a file: LC_ALL=C grep -nP '[^\x00-\x7F]' file.wls — anything in CODE (not comments) is a hazard.

RULE 2 — "license error" is a mis-reported crash; diagnose, don't believe it

When a heavy wolframscript job prints The product exited because of a license error:

1. Confirm the license is fine (it almost always is): wolframscript -code 'Print[{$LicenseType,DateString[$LicenseExpirationDate],$MaxLicenseProcesses}]' A valid, unexpired license + $MaxLicenseProcesses=Infinity means this is NOT a license issue.
2. It is a crash — the kernel hit a resource wall (almost always a memory spike from a huge symbolic intermediate) and wolframscript reports any abnormal kernel exit as a "license error." Ruled out in practice as causes: the Bash sandbox (disabling it does NOT help), ulimit (address space is unlimited), encoding, wall-clock time, and the license itself.
3. Localize it. Instrument the computation statement-by-statement with memory markers; the last marker before the exit is the culprit. Template:

   mb := ToString[Round[MemoryInUse[]/1024^2]]<>"MB";
   Print["[stmt] ", expr, "  mem=", mb, " t=", Round[AbsoluteTime[]]]; (* before each heavy line *)
   

4. Fix the spike (in order of preference):
   • Shrink the symbolic input first. The usual cause is keeping too many symbolic unknowns. If lower-stage results are already solved, substitute them in before the heavy step so the expression collapses (e.g. a product of two length-N symbolic lists is N²; substituting known values can drop N by orders of magnitude). This is the single highest-leverage fix.
   • Chunk huge products / Expands so the full intermediate is never materialized (Total[Table[Total[op[{a[[i]]}, b]], {i, Length[a]}]] instead of Total[op[a, b]]) — but note an N² operation is still N² operations, so this only helps memory, not time.
   • Run hygiene: put $HistoryLength = 0; at the top (stops Out[] retaining giant results); ClearSystemCache[]/Share[] between heavy steps.
   • Last resort: run it in the desktop / Wolfbook kernel (Mathematica FE), which has more headroom and different limits, then DumpSave the result for headless reuse. If the same code builds in the FE kernel but not headless, the headless wall is the cause — don't keep fighting wolframscript.