Troubleshooting

Where to look

Every report run is logged, with the settings it used and the exact engine command, in:

~/.local/state/io.github.pierrecagne.arxiv/digest.log

Problems with the widget itself show in the shell's log: find the instance with qs list --all, then run qs log -i <instance> | grep arxiv.

Listings

“arXiv is rate-limiting its API (HTTP 429)” or “Cannot reach arXiv”

arXiv's API sheds load this way, sometimes for hours, and is sometimes just slow. Each tab keeps its last list with the warning, and the plugin retries on its own, backing off from 2 minutes to the refresh interval. Nothing to do but wait; r forces a new attempt.

A tab stays empty

Check the category code against arXiv's taxonomy: math.CT, not Math.CT or category theory.

Reports

“The claude command is not on PATH” (or your command)

The helper runs with the environment of omarchy-shell, not of your terminal. If the engine is installed somewhere only your shell configuration adds to PATH, make it visible to the session, or use its absolute path in a custom command.

“This Claude Code has no --restricted mode”

The sandbox needs a recent Claude Code. Update it (claude update), or turn the sandbox off with omarchy bar set io.github.pierrecagne.arxiv sandbox false --json.

“Codex is no longer supported”

The engine setting still says Codex, which was removed. Pick Claude Code or Custom command in the widget's settings. Why.

“returned too little to be a report”

The engine answered with under 400 characters: usually an error message or a refusal. The log shows what it said. With a custom command, check that it prints to standard output and that the model's context window can hold a whole paper.

“The report style is Custom but the prompt file … does not exist”

Set promptFile to an existing file, or pick another reportStyle.

A report is wrong, or pitched at the wrong level

Make the reader description more specific, try another reportStyle or a stronger model. To regenerate a report, delete its Markdown file and press S.

Viewer

“Port 8791 is taken by another program”

Choose a free port: omarchy bar set io.github.pierrecagne.arxiv viewerPort 8795 --json.

“This address is out of date”

The viewer has restarted since the page was opened, for example after you logged in again, and its addresses changed with it. Press v in the widget to open the reports again.

The mathematics does not render

The first time the viewer starts, it downloads KaTeX; if that failed, the pages load it from the CDN instead, which needs a connection. The download is retried the next time the viewer starts, for example after you log in again.