The rest
Troubleshooting
The things that actually go wrong, and what to do about each one.
Windows says "unknown publisher"
Expected. The installer is not code-signed yet. Choose More info, then Run anyway.
A signing certificate is on the list. Until then this warning appears for everybody, which is why the download page says so before you meet it.
On a Mac there is no warning to get past: the Mac app is signed and notarized by Apple.
A browser extension blocked the download
Malwarebytes Browser Guard and similar tools flag it as "suspicious content". Nobody reported the site: a heuristic fired, and four things happened to be true at once. The domain is new and on a .xyz, the download link carries a token, it redirects to a different host to fetch the file, and the file is a large unsigned executable.
That is the shape of malware delivery. It is also the shape of a legitimate licensed download, and the heuristic cannot tell them apart. Signing the Windows installer removes the strongest of the four signals.
The model picker says an engine is missing
The CLI is not installed, not signed in, or not where Pragma looked.
- Run the CLI in a terminal and finish its sign-in.
- Restart Pragma.
- Still missing: Settings, then Engines, and set the executable path explicitly.
The explicit path is the reliable fix for version managers, wrapper scripts, unusual install locations, and for launching Pragma from a shortcut whose environment differs from your terminal's.
An engine returns 401 partway through a task
Authentication belongs to the CLI. Finish that tool's own login, then refresh detection in Settings. Retrying the task will keep producing the same error.
No update card ever appears
You are on 1.3.14 or earlier. Those builds never check. Download the current version once from trypragma.xyz. See Updates.
On a Mac, Pragma is running from the disk image. A copy opened straight from the .dmg cannot replace itself. Quit it, drag Pragma into Applications, and open it from there.
I cannot find my licence key
Search your inbox, spam included, for Your Pragma licence key. Then use Email my key on trypragma.xyz/thanks with the address you bought with; your purchase receipt shows which one that was.
If it still does not arrive, email systo.ai@gmail.com from the address you paid with. See Your licence key.
A routine did not run
Its receipt will say missed, which means Pragma was not open when it came due. Routines are local: there is no server of ours running them while your machine is off.
The phone cannot reach the companion
Both devices need to be on the same network. Pragma does not open a route through your router and does not relay through anything of ours. Check that the companion is still switched on in Settings, and that the desktop is awake.
A run keeps disconnecting
Transient failures retry on their own. If it settles into a repeated authentication or configuration error, fix the engine rather than the task. The Inspector shows what actually happened, which is usually more useful than the conversation at this point.
A local model says the request exceeds its context size
The model is loaded with a smaller context window than one turn needs. Most of a turn is not your message: the engine sends its own instructions and tools with every message, which comes to over 35,000 tokens for the Qwen engine and about 45,000 once connected apps are on. A model loaded with a 32K window fails before your message is read, so a shorter message will not help.
Pick a model that can hold more. Before a turn uses an LM Studio model, Pragma loads it with a 64K window, or with as much as the model allows if that is less, and the conversation says so while it loads; a big model read from disk the first time can take a minute. The model picker shows the window of each loaded local model and marks the ones under 64K. Some models stop at 32K, qwen2.5-coder-14b-instruct among them, and for those the answer is a different model. Pragma's own local models, under On this computer in the model picker, start with a 128K window, or 64K on a graphics card that cannot run the smaller cache that makes room for 128K.
If LM Studio cannot load it, the conversation says so, and that is usually memory. Pragma first tries again with the context kept in system memory rather than on the graphics card, which is slower and often fits. When that fails too on Windows, the paging file is the usual limit: raise it under System, Advanced system settings, Performance, Virtual memory, on a drive with room to spare.
With Ollama, the context length is the model's num_ctx, set in its Modelfile or in Ollama's settings.
Local models are missing on my Mac
Pragma's own local models run on Macs with Apple silicon, not on Intel Macs, which cannot run them fast enough for an agent. On an Intel Mac, use an engine that runs on your subscription or API key instead: see Engines and models.
Something else
Open Settings, then Support, say what went wrong, and send it. Add a screenshot or a short video if it helps show the problem, of the Pragma window, another window, or a whole screen: you pick which, and Settings closes while you take it so it stays out of the picture. Every report is read. If you give an email, a confirmation with the reference arrives there shortly, and the reply follows in the same thread.
What goes with a report:
- your message, and the email you give for the reply
- the screenshot or video, if you add one, of the window or screen you picked and nothing else
- unless you untick it, the diagnostics: your Pragma version, which settings are on (never their keys) and recent log lines, with anything secret removed
Screenshots, recordings and diagnostics are deleted after 90 days.
When Pragma will not start at all, email systo.ai@gmail.com with your Pragma version, the engine you were using and what happened.