Errors and logs
Why a plugin's page does not load, in plain words with the fix as a button, and the log file that has the same words
When a plugin's page cannot load, its card says why, with the fix as a button. The same words go to the plugin's log, where an author or an agent reads them.
Errors in the card
The card shows the plugin's icon, a title, the details in 12 pt monospace (selectable, at most 12 lines), Show Log, and the fix:
| Title | When | Details | Button |
|---|---|---|---|
| "‹name› needs Node.js" | no npm, pnpm or bun on the login PATH | "Ovvi installs and builds plugins with npm, pnpm or bun, and none is on your PATH. Install Node.js from nodejs.org, then try again." | Try Again |
| "‹name› could not install" | a default plugin's first install failed (offline, a failed npm ci) | the command's last 20 lines | Try Again |
| "‹name› is not installed" | a default plugin's copy is missing and no install failed | none | Try Again |
| "‹name› did not build" | the build script failed | the script's last 20 lines | Try Again (builds again) |
| "‹name› is not built" | the entry (dist/main.js) is missing | "dist/main.js is missing. Build runs its build script." | Build, or none when the package has no build script ("build it with its own tools") |
| "‹name› stopped" | main threw, or the page did not load | the error's message and its first stack line | Reload |
| "‹name› needs a newer Ovvi" | the manifest's api is above the app's | "It is written for version ‹n› of the plugin API; this Ovvi has version 3." | none |
| "‹id› did not load" | the manifest is wrong; shown on the missing-plugin card when the ovvi.id reads | the file and the field: …/package.json: ovvi.entry is missing | Show Placeholder, Close Pane |
- A default plugin installing on first launch shows "Installing ‹name›…" with a spinner, not an error.
- The confirmation is not an error: the card of a plugin that you did not confirm yet asks first (Security and trust).
- A failed Reload Plugin keeps the running page. Its toast says the title and the first line, with Try Again (Reload).
- A crashed page (the system ended WebKit's process for it, for example under memory pressure) loads again by itself, once per load. Unsaved edits are lost then. A page whose process ends again before it loaded shows "The page stopped working" with Reload, so it never stays blank. A card out of view shows it too, when its process ends again while the page loads in the background.
- A blank page after WebKit's GPU process stopped answering draws again by itself where it was, with no reload (Browser).
- The Plugins page in Settings shows a failed install, update or remove on a red notice: "package.json: ‹field› ‹what is wrong›", or the first of the command's last lines, with Retry when running it again can help.
The log
Each plugin has a log file: ~/Library/Logs/Ovvi/plugins/<id>.log. Every
line starts with its time (ISO 8601). A line from a page that has line breaks
goes on indented, so it never reads as the app's own line. Past 1 MiB the file
starts over.
What goes in:
- Every build: "built in ‹n› ms" and the script's output, or the error card's words.
- Installs and updates: "installed from ‹source›" and the package manager's output, or what failed.
- Each
consoleline of the page, with its level (log,info,warn,error,debug), and every uncaught error and rejected promise, also one thrown in a handler of an app event (ovvi.on). - A command whose key the app already uses: "the key cmd+t of the command ‹id› is the app's: it is left off".
- A page that stopped, and an API too new.
- A manifest that the registry left out: its file and field, or "the id ‹id› is taken by ‹folder›". It goes to the log named after the package's folder. A bad manifest also goes to the id's log when the id reads.
Show Log opens the file in the app for .log files (Console). It is in
the card's menu (also View ▸ Pane and ⌘K), on every error card, and on each
plugin's page in Settings.
An agent reads the file directly:
tail -f ~/Library/Logs/Ovvi/plugins/csv-table.logA manifest left out is also in the unified log:
log show --predicate 'subsystem == "dev.ovvi.app"'. A build of your own
logs under its own bundle id, such as dev.ovvi.app.debug.
Choices
The decision is D102 on the Decisions page.