4. Limits per function

Numbers taken from the code and measured, with NOTUSBASE_DEV_ERRORS=1 to see the message. The ceilings for documents, bytes, time, memory, scheduler and files, and their texts, come from Convex: a test triggers each one in both systems and compares. Defaults are changed through server environment variables; there is no per-function or per-project limit.

On the dashboard. Home → Limits lists every limit of the server, these and the others, with the ceiling as the server applies it, how close your app got (the highest value per call since the server started, and the function that reached it) and what to do; see Limits and problems.

Limit errors can be caught. try/catch catches the read, write, large-document and scheduler errors, and the function carries on: a mutation commits what got through. The counter does not go back, so whoever caught the error stays at the ceiling. A nested ctx.runMutation that fails rolls back what it wrote, but not what it read or scheduled. Only time and memory cannot be caught.

Per query, mutation and action call

What counts as a read. Every row the query looks at, as in Convex: the ones it returns and the ones a filter discards. The filter becomes a WHERE in SQLite, so the discarded row never reaches JS, but it counts as a document read (measured on 2026-11-09: with the read ceiling at 5, a filter over 12 rows that returns 1 fails with Too many documents read in a single function execution (limit: 5)). Only its bytes are left out of the 16 MiB. The 1 s time limit also interrupts SQLite in the middle of a scan. On a large table, always use withIndex.

What accompanies a function. ctx.meta.getTransactionMetrics() returns the usage and what is left of each ceiling above, with Convex's 11 keys.

paginate does not hit the ceiling. Reaching the read ceiling in a page ends it with pageStatus: "SplitRequired" and splitCursor. The error only comes out if not even the first document fits. maximumBytesRead cuts the same way. SplitRecommended warns above 3/4 of the byte or row ceiling (default: 32,000), or with more than 6,144 items. numItems above 32,000 gives Requested too many items.

Concurrency and writing

A slow mutation (more than 20 ms of function) on a heavily contended row is the only case where the client sees a conflict error.

Disk error at commit. With the data disk full, a commit can fail with "disk I/O error" after its frames are already in the WAL file. SQLite takes the write as undone, but a crash or a stop with the disk still full would bring it back as committed at the next start. So before answering, the writer cuts those frames off the WAL file. That frees space and needs none, so the write is refused for good and the client gets the usual error. If the cut fails too:

• The calls in that commit get Write outcome unknown: the server hit a disk error while committing. The write may appear later, even after a restart. Read before retrying. A disk I/O error at commit is an unknown outcome: the write may appear after a restart. A scheduled function that gets it is not run again.
• Every later mutation gets Writes are paused after a disk error. Nothing was written. Reads still work; free disk space on the server., and the dashboard shows Writes are paused after a disk error (runbook). The writer tries the cut again on the next mutation, at most once a second, and resumes by itself. Queries and subscriptions go on.
• What the pause holds: writes from functions, which all go through the writer (mutations, including those an action, an HTTP action or the scheduler runs). Writes PocketBase makes by itself (the records API, sign-in, the admin dashboard) and the logs in auxiliary.db do not go through it: they are not held while paused, and if one of them hits the same disk error its frames are not cut, so a crash before the next commit could still bring that one back.

Transport

A file inside a function. What each path holds in memory, measured on 2026-11-07 on the Mac (the process RSS above the 94 MB at rest, and the isolate's peak in MB; the Mac was loaded, so the memory counts and the time does not):

For the 50 and 200 MB files, most of the "after" is the Blob the action built: the measurement fixture (notusbase/app/convex/bigfile.ts) creates the file and new Blob([...]) copies it, three ArrayBuffer copies outside the heap (external of 607 MB with a 200 MB file). Building the same Blob without storing it gives RSS +605 MB and external of 600 MB, and storing adds less than 10 MB. The cost of store itself is then the 1 MiB chunk plus what Go holds (one chunk, the temporary file on disk and the hash).

ctx.storage.store(blob) and ctx.storage.get(id) in an action pass the file in 1 MiB chunks. The upload goes straight to a temporary file on disk, with the hash computed along the way, and the read comes out of the file one chunk at a time into a single Uint8Array, which becomes the Blob without copying. The Blob stays whole inside the action, because the API takes and returns it whole; it is the only copy left (1x the file, outside the heap, counting toward the isolate's 1 GiB of ArrayBuffer). The ceilings on the path:

• Storing in an action: no size ceiling of its own. The isolate applies (1 GiB of ArrayBuffer) and, if the file comes from fetch(...).blob(), the 64 MiB of the body. For a larger file, use the upload link (generateUploadUrl), which writes straight to disk up to NOTUSBASE_UPLOAD_MB.
• Reading in an action: 20 MiB, as before; the refusal now comes before the file is opened.
• Mutation: still base64 and all at once (16 MiB ceiling, 1 s wall clock), because the ceiling already bounds it. The 1 s applies to the whole mutation.
• fetch with a large request body still converts the whole body to base64 (not storage).

In a mutation, ctx.storage.store writes the file right away, outside the writer, and the _storage row joins the transaction. If the mutation fails or hits a conflict, the file is deleted, and the conflict stores it again on retry. A server crash in the middle leaves a file without a row, which nobody can reach; never the other way around.

Compared with Convex

The Convex numbers are the ones on the official limits page (docs.convex.dev, read on 2026-11-06), Pro plan. They tell you what changes when you migrate.

How to protect yourself

• Time: an index on every read of a table that grows, and take(n)/paginate instead of collect().
• Reads: when a screen needs more than 32,000 documents, keep an aggregate in a table (counters updated in the same mutation) instead of summing at read time.
• Bulk writes: split into batches and chain them with ctx.scheduler.runAfter(0, ...), one mutation per batch (example: maintenance.cleanOldEvents in the example project).
• Memory: do not build large lists in the function. In an action, avoid loading a whole file.
• An action that blows CPU or memory affects the ones sharing the isolate. Keep actions small and free of heavy loops.