Limits and Troubleshooting

Limits and Troubleshooting

What openToolbox is not

• Not a multi-user system. No accounts, no roles, no server-side access control — because there's no server. Two people editing "the same" file independently produce two divergent truths; reconciling them is a manual, out-of-band exercise (compare, merge by hand, or agree on one editor at a time).
• Not a database with a query language. Filtering, sorting and search are all in-memory operations over whatever's in the payload; there's no indexing strategy to reason about beyond "how many records fit comfortably in a browser tab."
• Not a shape-shifter. It's a records-with-fields tool: list, filters, a form. A calculator, a canvas, a diagram editor, or a wizard doesn't fit the shape — see Building Your Own Tool for what to do instead.
• Not a real-time collaboration tool. There's no shared state, no live cursors, no conflict resolution — each file is a single, self-contained snapshot.

Limits worth knowing before they surprise you

• Not saved means lost. There is no autosave — without a target file to write to, there cannot be one. The amber dot in the file bar and a tab-close confirmation prompt are the only safety net. Ctrl/Cmd+S saves.
• One machine, one file, at a time. If you need the appearance of shared state, the pattern is: one person edits, saves, hands the file to the next person — not simultaneous editing.
• Mail gateways strip .html attachments more often than not, treating them as a phishing risk (which, generically, .html attachments often are). Zip the file before sending, or use a proper file-transfer channel — and test the actual route once with a dummy file before it matters for something real.
• Encryption protects the data, not access to the app. See Security and Encryption for the full reasoning — the short version is: whoever has the file has the code, always.
• No recovery from a lost passphrase. This is intentional, not an oversight — a back door would defeat the point of encrypting in the first place.

Common failure modes, and what they actually mean

The build produces a tiny file (a few KB) that renders nothing

Almost always removeViteModuleLoader: true set in vite.config.js, or something else that strips the inlined script block. Don't set that option — see Building Your Own Tool. The CI build check in .github/workflows/build.yml fails loudly on exactly this (size -lt 40000 bytes triggers an explicit "Build far too small" error), so it shouldn't reach a release unnoticed.

The AI integration says "the request never left the browser"

This is the CORS-from-file:// situation, not a bug — see AI Assistant. From a local file, the request origin is literally "null", and most API providers (including api.openai.com directly) don't allow that origin. Put a proxy in front that does (LiteLLM, an API gateway, a small serverless function).

The AI integration keeps retrying and eventually fails

Means the client tried up to six adaptations of the request shape and none were accepted — check that the model name and endpoint are actually correct first; a wrong model name often surfaces as a generic 4xx that looks like a dialect problem but isn't one.

A saved file won't open, or looks corrupted

The payload block (<script id="sb-payload">) may have been altered outside the app — e.g. by an editor that "cleaned up" whitespace, or a mail/proxy service that rewrote the HTML in transit. The app falls back to an empty/fresh state and logs a console warning rather than crashing outright, but the previous data in that particular copy is gone; restore from a backup copy of the file if one exists.

A hand-edited or partially-filled configuration import "loses" fields

Not a bug — importConfig (Settings → Configuration → Load) validates every field against the current settings shape: anything it doesn't recognize is dropped and named in the resulting notice, and a value of the wrong type falls back to the default rather than being accepted as-is. This is deliberate, per Branding — it's what keeps a stale or hand-edited config file from silently corrupting settings instead of degrading safely.

Reporting a problem

Include: browser and version, whether the file was opened via file:// or served over HTTP, and the built file's size. A build around 9 KB is a different bug (the inlining failure above) from anything behavioural. See Contributing for the full ground rules.