DEV Community: stale_orbit

NocoBase in Docker: a fine place to run, a poor place to build

stale_orbit — Mon, 10 Aug 2026 01:57:31 +0000

The NocoBase plugin development docs assume one of two starting points: a project created with create-nocobase-app, or an installation from the Git source. Neither is what most people actually have in front of them. What you have is the container you spun up with docker compose up -d a week ago, database already populated, and building a plugin there would obviously be quicker.

Someone tried exactly that and posted about it on the official forum (t/12732, May 2026): compilation failed in the Docker environment because @nocobase/devtools wasn't installed. The thread ends with one reply asking for a full tutorial, and nothing after that. The report is also from the 2.0 line.

So I ran it end to end on 2.1.23. You can make it work — but you shouldn't, and the reason isn't the two missing dependencies. It's what happens afterwards.

Test setup: NocoBase 2.1.23 (official Docker image nocobase/nocobase:2.1.23) + PostgreSQL 16. Everything done through the CLI inside the container (yarn pm, yarn build), with the implementation in @nocobase/cli-v1 read where behavior needed explaining.

Obstacle 1: scaffolding reports success and produces nothing

yarn pm create @scope/plugin-hello

It ends with Done in 5.57s. and exit code 0. Then:

$ ls /app/nocobase/packages/plugins/
.gitkeep     # nothing new

Scrolling back through the output, there's an error buried in it:

Cannot find module '@umijs/utils'
Require stack:
- /app/nocobase/node_modules/@nocobase/cli-v1/src/plugin-generator.js

The generator module can't resolve a dependency and dies, while the command as a whole still exits successfully. If you don't read the log you're left hunting for a directory that was never created. I hunted for a while.

The fix is what it looks like:

yarn add @umijs/utils -W

After that the scaffold appears, including the V2 page entry points:

packages/plugins/@scope/plugin-hello/
├── package.json
├── src/index.ts
├── client.js / client.d.ts
├── client-v2.js / client-v2.d.ts
└── server.js / server.d.ts

Obstacle 2: the build asks for "all dependencies"

yarn build @scope/plugin-hello

Please install all dependencies
$ yarn install
error Command failed with exit code 1.

This one fails honestly — exit code 1 — but the message doesn't say which dependency. The check turns out to be a single condition:

// @nocobase/cli-v1, util.js
exports.hasTsNode = () => exports.isPackageValid('ts-node/dist/bin');

exports.nodeCheck = () => {
  if (!exports.hasTsNode()) {
    console.log('Please install all dependencies');
    process.exit(1);
  }
};

It only looks for ts-node. What brings ts-node along is @nocobase/devtools — the package named in the forum report.

yarn add @nocobase/devtools@2.1.23 -W -D    # match your app version

Now the build runs:

Rspack 1.7.8 compiled successfully in 38 ms
@scope/plugin-hello: build plugin server source
@scope/plugin-hello: build declaration
Done in 8.99s.

And yarn pm enable @scope/plugin-hello reports success. At this point the forum report is confirmed: add two dependencies and you can build plugins in the Docker image.

The interesting part starts here.

Obstacle 3: recreate the container and it's all gone

Sooner or later you bump an image tag or change a setting, which means docker compose down && docker compose up -d. Afterwards:

the plugin           : No such file or directory
@nocobase/devtools   : No such file or directory
@umijs/utils         : No such file or directory

Obvious in hindsight — all of it lives in the container's own filesystem layer. The only thing that survives is whatever a volume is mounted onto, which in a standard setup is exactly one path:

volume nocobase-storage -> /app/nocobase/storage      # the only survivor

Plugins are scaffolded into packages/plugins/, which is outside that. (storage/plugins/ did still hold its contents after the recreate, which matters for the recommendation below.)

And then it runs while broken

The files are gone. The database still says the plugin is installed and enabled:

SELECT name, enabled, installed FROM "applicationPlugins" WHERE name = '@scope/plugin-hello';
 @scope/plugin-hello | t | t

So every startup logs this:

Cannot find plugin '@scope/plugin-hello'
  at PluginManager.getPackageJson (...)

And the application returns HTTP 200 and serves traffic normally. It doesn't crash, which is precisely the problem: without reading the logs you have no signal at all. I ran into the same "boots fine, internally broken" shape once before, when testing a version downgrade — NocoBase does not stop for this class of inconsistency, so you need your own way of noticing.

Cleanup is one statement:

DELETE FROM "applicationPlugins" WHERE name = '@scope/plugin-hello';

What to do instead

Build somewhere else. The reason the docs assume create-nocobase-app or a Git checkout is that those give you an environment where the tooling is present and your work doesn't evaporate. The Docker image is built for running: its devDependencies are empty, which is a deliberate choice rather than an oversight. Fighting that costs more than it saves.

If you insist on Docker, give the output somewhere to live. Mount packages/ from a volume or a bind mount and at least the plugin survives. The dependencies won't — they land in node_modules — so you're reinstalling them after every container recreate. Automating that is more work than standing up a proper development environment.

Let the Docker instance be the thing that runs. Build elsewhere and bring the result in through storage/plugins/, which is volume-backed. Which is to say: separate building from running, the way you would with anything else.

One more thing, if you're behind a corporate proxy

On a network with TLS inspection, yarn add inside the container fails with self-signed certificate in certificate chain. Copy your CA bundle in with docker cp and point both NODE_EXTRA_CA_CERTS and yarn's cafile at the copy.

Copy it — don't bind-mount the host's system CA file into the container. That's a good way to damage the host's certificate store, which I mention because I have done it.

Takeaways

Stepping outside the documented prerequisites costs two missing dependencies: @umijs/utils for scaffolding, @nocobase/devtools (for ts-node) for building.
pm create exits 0 even when it fails. Read the log; don't trust the status code.
Those fixes work — until you recreate the container, which erases the plugin and the dependencies alike. Only volume-mounted paths survive.
Afterwards the database still lists the plugin as enabled, so the app logs an error on every boot and returns HTTP 200 regardless. Nothing crashes, so nothing tells you.
Use the Docker image to run, and build in the environment the docs assume.

The instinct to use the environment already in front of you is a reasonable one. In this case the cost of stepping outside the assumptions came back in full. My guess is the forum report stopped at "add the dependency and it compiles" simply because nobody carried it as far as recreating the container.

(Measured on 2.1.23 / PostgreSQL 16. Behavior may change in future versions.)

References

NocoBase API keys: tight permissions, loose key management

stale_orbit — Wed, 05 Aug 2026 03:33:41 +0000

In a previous post about where the Community edition's limits actually sit, I mentioned a workaround for the webhook trigger being a paid feature: create a role whose write permission is scoped to a single table, issue an API key for it, and have the external system POST to the REST API directly. Someone on the official forum runs exactly that in production, receiving pushed data from a bank.

Recommending something without testing it sat badly with me, so I built it and hammered on it. The good news: the permission model holds up exactly as advertised. The less good news: three operational behaviors caught me out, and two of them let you end up with keys that look alive in the list while being dead in practice.

Test setup: NocoBase 2.1.23 (official Docker image) + PostgreSQL 16, driven entirely through the REST API. Where behavior was surprising I read the implementation in @nocobase/plugin-api-keys and @nocobase/acl to confirm the mechanism.

Most of what follows bites when you automate key issuance through the API. Creating keys by hand in the admin UI avoids all but one of them — and that one is the most consequential. There's a routes-vs-pitfalls table near the end.

An API key is a role, wearing a token

A NocoBase API key carries no permissions of its own. It's a JWT that encodes which user, acting as which role:

{"userId": 2, "roleName": "integration", "iat": 1785120716, "exp": 33342720716}

Two things to notice. First, the key's authority is exactly the role's authority — nothing more, nothing less. Second, there's no jti — no per-key identifier. That absence causes the third surprise later.

(An "unlimited" expiry still writes an exp; the implementation just substitutes a date far in the future.)

Scoping works as advertised

I built a role allowed to do exactly one thing — create on an inbound_orders table — and issued a key for it:

Request with that key	Result
`create` on the permitted `inbound_orders`	200
`create` on a different table	403
`list` on that same `inbound_orders`	403
`list` on `users`	403

Note the third row: same table, but read access is refused because only create was granted. The granularity is per-action, not per-table. As a credential to hand an external system, that's tight enough to be comfortable.

Role edits take effect immediately, without reissuing

I left the key untouched and changed the role instead:

grant internal_memos:create to the role  → same key, create → 200
revoke it again                          → same key, create → 403

No redistribution needed when requirements change. The flip side is worth stating plainly: widening a role widens every key already issued for it. Use one role per integration.

Letting regular users issue keys — and the ACL rule that blocks it

By default only administrators can create keys — a regular account gets 403 No permissions. To open it up, grant the role the pm.api-keys.configuration snippet. That's where I lost some time.

The stock role carries ["!pm", "!pm.*", "!ui.*"]. Adding the specific grant on top of that does nothing:

Snippet configuration	Result
`!pm`, `!pm.`, `!ui.`, `pm.api-keys.configuration`	403
`pm.api-keys.configuration`, `!pm`, `!pm.`, `!ui.` (order reversed)	403
`!pm`, `!ui.`, `pm.api-keys.configuration` (drop `!pm.`)	200

The ACL implementation collects allows and denies separately, then folds them like this:

// from @nocobase/acl, effectiveSnippets()
const effectiveSnippets = new Set(
  [...allowedSnippets].filter((x) => !rejectedSnippets.has(x))
);

Anything matched by a deny is dropped, no matter how specifically it was allowed — and order is irrelevant. If your instinct comes from IAM or CSS, where specificity or ordering decides, that instinct is wrong here. You can't carve an exception out of a wildcard deny; you have to narrow the deny itself.

Surprise 1: omit the role and you get a cheerful 200 with nothing behind it

This one is specific to the API — the UI has a mandatory role selector.

Leave role out of the create request and you get:

POST /api/apiKeys:create  {"name": "my-key", "expiresIn": "never"}
→ HTTP 200
→ {}

Success status, no key, no error. The implementation explains it:

// @nocobase/plugin-api-keys, create
async function create(ctx, next) {
  const { values } = ctx.action.params;
  if (!values.role) {
    return;          // returns without a word
  }

If your provisioning script treats 200 as "key created", it will sail past this. Check that the response body contains token, not just the status code.

Surprise 2: nobody can inventory the keys — not even root

Of the three, this is the one that applies whichever route you use, and it has the largest operational consequence.

Keys issued by a regular user simply don't appear in an administrator's list:

the user's own list        : ['integration-key', 'clean-key', 'gov-key', ...]
the administrator's list   : ['admin_api_key']        ← only their own
rows actually in the DB    : 14

My first thought was that I'd tested with an underpowered account. I hadn't: it held root, admin and member, and passing X-Role: root explicitly returns the same single key. The reason is a server-side middleware that rewrites the request unconditionally:

// applied to list / destroy
ctx.action.mergeParams({ filter: { createdById: ctx.auth.user.id } });

No role check anywhere, which means no amount of privilege routes around it — and because the admin UI calls the same REST endpoint, using the UI doesn't help either.

As "you can't read other people's credentials", this is sound design. As operations, it means there is no way to answer "how many keys are live right now, and who holds them?" from inside the product. If you need that answer, query the apiKeys table directly (it carries createdById). And if you're considering opening key issuance to regular users, weigh it against this: you'd be handing out credentials you cannot subsequently enumerate.

Surprise 3: keys issued in the same second are the same key

Also an automation-only problem in practice — issuing two keys within one second by hand is difficult. It's still the one that fooled me longest.

I issued two keys back to back for the same user, role and expiry, then compared the token strings:

token(twin-a) == token(twin-b)  →  True

Look again at the payload: userId, roleName, iat, exp, and no jti. Since iat has one-second resolution, two keys created inside the same second with the same parameters serialize and sign to a byte-identical string. Space them more than a second apart and they differ.

Because both carry the same role, this isn't privilege escalation. The damage shows up at revocation time:

call the API with twin-b   → 200 (alive)
revoke twin-a              → 200
call the API with twin-b   → 401 ← never touched it
is twin-b still listed?    → True ← still looks alive

Revocation works by adding the token string to a blocklist, so a second record holding the same string dies with it. Issue keys one at a time, with a gap.

The same asymmetry, from the admin side

An administrator can't see another user's keys, but the id is readable straight from the apiKeys table. Point the revoke endpoint at that id and:

Check	Result
Row still in the database	yes
Still listed for its owner	yes
Key still usable	401

Revocation happens in two steps, and they disagree about ownership. The first — blocking the token — looks the row up with a raw findById that skips the ownership filter. The second — deleting the row — goes through the filtered action from Surprise 2. So the credential dies while its record survives.

The operational takeaway is short: once a key starts returning 401, stop trusting the list. A row being there doesn't mean the credential works. Reissue and move on.

Which of these actually apply to you

Behavior	Issuing via API	Issuing via UI	Why
1. Silent 200 with no key	applies	not applicable	the UI requires a role selection
2. Keys can't be inventoried	applies	applies	enforced server-side; the UI uses the same endpoint
3. Same-second token collision	applies	effectively not	issuing twice within a second by hand is impractical
3b. Revoked-but-still-listed	applies	not applicable	admins can't see others' keys to target an `id`

If you provision keys by hand, only the second one is your problem — but it's a real one, because it quietly invalidates the assumption that the admin console shows you what's out there. Start automating issuance and the rest arrive together. That transition is exactly when this post is worth rereading.

Checklist

One role per integration. Widening a role widens every key already issued under it.
Scope by action, not just by table. A receive-only integration should not be granted list.
Don't try to except your way out of a wildcard deny — deny wins, regardless of order.
When provisioning via API, always send role, and verify token is in the response. A 200 alone proves nothing.
Issue keys one at a time, spaced more than a second apart.
Track issued keys outside the product. The admin console cannot enumerate them, so keep a register — or query the database.

(Measured on 2.1.23 / PostgreSQL 16. Behavior may change in future versions.)

References

NocoBase says the free edition builds "unlimited applications" — here's what that actually means

stale_orbit — Tue, 28 Jul 2026 02:23:12 +0000

If you're evaluating NocoBase, you hit this question early: how far does the free Community edition actually go?

The pricing page says the Community edition lets you:

Build unlimited applications with no limits on users or data

Sounds generous. Then you open the docs, look up anything multi-app related, and every page carries a paid-edition badge. So can you build "unlimited applications" for free or not?

It turns out someone asked the official forum exactly this, and a staff member settled it. This post maps the Community/paid boundary using only primary sources — the pricing page and official staff answers on the forum (several of them in the Chinese-language category, which is by far the most active and where a lot of these answers live).

Everything below reflects the pricing page and forum answers as of July 2026. Editions and prices change; check the pricing page before making a purchase decision.

What "unlimited applications" actually means

The forum question (t/13365, July 2026, Chinese) was word-for-word the confusion above: the pricing page says unlimited apps, the multi-app docs all say paid edition — which is it?

The staff answer (translated):

The Community edition lets you deploy and develop multiple mutually independent application instances. But "multi-app" refers to the feature of creating and managing multiple isolated applications inside a single NocoBase. Using that feature in a newly installed environment requires the Professional edition.

So:

"Unlimited applications" = you can stand up as many NocoBase instances as you want. Ten Docker containers running ten systems is fine — it's open source, after all.
The multi-app feature — managing multiple isolated apps inside one NocoBase — is paid.

If you read "build unlimited applications" and expected the multi-app feature, you'd be disappointed — and judging by the forum, plenty of people read it exactly that way. I'd argue that's on the wording, not the readers.

One more wrinkle worth knowing: the pricing page lists multi-application architecture under Enterprise, while the forum answer above says Professional. If multi-app is the reason you're buying, confirm the required edition with the team directly before you pay.

The "wait, that's paid?" list

Pulling from the edition comparison on the pricing page, here's where the boundary actually sits. These are the ones most likely to surprise you:

Feature	Edition
Rebranding (logo / product name)	Standard
External database connections (supported DBs vary by edition — see below)	Standard and up
Bulk Excel import/export	Standard
Approval workflows	Professional
Subflows	Professional
Webhook trigger	Professional
SSO / record edit history	Professional
Audit log (user action logging)	Enterprise
Multi-app / multi-space	Enterprise (forum says Professional — see above)
Cluster deployment	Enterprise

Three of these bite hardest in practice:

Approval workflows. Request-then-approve is the bread and butter of internal tools, and the Approval plugin is Professional. To be precise: the Community edition does have a generic Manual Handling node (pause until a human acts). What's paid is Approval — the dedicated plugin with request lists, approval screens, and the rest of the purpose-built UI.
Webhook trigger. The official path for receiving data from external systems sits on the paid side. There's a solid workaround, though — next section.
External databases. Layering NocoBase on top of an existing business DB starts at Standard ($800), and the supported engines depend on the edition: MySQL / PostgreSQL / MariaDB at Standard, MSSQL and REST API data sources at Professional, Oracle / ClickHouse / Doris at Enterprise.

No webhooks? You can still receive data

In another thread (t/13337, July 2026), someone needed to receive pushed data from an external service. After a reply pointed out that webhooks require Professional, a practitioner shared what they run in production (translated):

Create an API key, and give it a role whose write permission is restricted to just the table you're storing into. The external service writes directly through the REST API. This is how we currently receive pushed data from a bank.

Every NocoBase collection automatically gets a REST API, so "receive via webhook" becomes "have the sender write via REST" — fully within the Community edition. The key detail is the locked-down role: API keys inherit the role's permissions, so a key scoped to one table limits the blast radius if it ever leaks.

(If you needed the webhook specifically to trigger a workflow on arrival, bind a collection event to the target table instead — with the caveat that collection events have their own quirks, like not firing on bulk operations.)

You can't buy plugins individually anymore

One more boundary fact that trips up budgeting. There was a period when commercial plugins could be purchased one by one. Asked about buying just the report-printing and subflow plugins (t/12377, May 2026), staff answered (translated):

That's no longer supported. You need to purchase a license, and the license includes the corresponding plugins.

So the current model is: buy an edition license, get that edition's plugin set. If the one feature you need lives in Professional, your unit of purchase is Professional ($8,000, one-time) — there's no à-la-carte option. Plan budgets around editions, not features.

To be fair: the free side has been growing

Lest this read as "the free edition is bait" — the movement in 2026 has been in the other direction. In February, the core license changed from AGPL-3.0 to Apache-2.0, and 16 previously-commercial plugins were open-sourced in the same move.

The realistic summary: a single internal business system, without approval flows, is entirely buildable on the Community edition. The paid line is drawn around approvals, the official external-integration path, unified multi-app management, and enterprise operations (clustering, audit logging).

Evaluation checklist

"Unlimited apps" means unlimited instances. Managing multiple apps inside one NocoBase is paid — and the required edition (Professional vs Enterprise) is stated inconsistently, so confirm before buying.
Ask "do we need approval workflows?" first. It's the most common late surprise. If yes, budget for Professional from day one.
No webhooks needed for inbound data — a write-scoped API key plus the auto-generated REST API covers it.
No per-plugin purchases. Find which edition contains your must-have feature and price that edition.
Editions and prices move; re-check the pricing page (and ask the team directly for edge cases) before deciding.

References

NocoBase and the mystery of the shifted timestamps: MySQL vs PostgreSQL, measured

stale_orbit — Thu, 23 Jul 2026 00:50:56 +0000

There's a class of bug reports that keeps coming back in the NocoBase community, especially in the Chinese-language forum: "all my times are off by 8 hours" or "dates show up as the day before." China is UTC+8, so the shift is 8 hours there. I run my instances at UTC+9, and sure enough — my shift is 9 hours. Whatever your offset is, that's the size of your shift.

That pattern is a strong hint that this isn't random corruption. It's a mechanism. I set up NocoBase 2.x against both PostgreSQL and MySQL and measured what actually gets stored and how it gets reinterpreted, until the mystery had a concrete answer.

Test setup: NocoBase 2.0.51 and 2.1.23 (official Docker images) × PostgreSQL 16 and MySQL 8.4. All data written and read through the REST API, with the server timezone controlled via the container's TZ environment variable. I'm deliberately ignoring the browser-side rendering here — this is about what the server stores and how it interprets it.

Background: 2.x has four datetime field types

NocoBase 2.x collections offer four datetime-ish field types (official list — though several of the per-type detail pages still say "To be added", which is exactly why I measured instead):

Type	What it's for
Datetime (with time zone)	Absolute instants — event start times, logs
Datetime (without time zone)	Wall-clock times you want preserved as-is
Date only	Birthdays, due dates, anniversaries
Unix timestamp	System integration

Measurement 1: what each type actually stores

I imported "2026-07-12 09:00" via xlsx and looked at the raw values in each database (identical on 2.0.51 and 2.1.23):

Field type	PostgreSQL	MySQL
Datetime (with TZ)	`timestamptz` → `2026-07-12 09:00:00+09` (an absolute instant, offset included)	`DATETIME` → `2026-07-12 09:00:00` (wall clock only — no offset information)
Datetime (without TZ)	`timestamp` → `09:00:00`	`DATETIME` → `09:00:00`
Date only	`date` → `2026-07-12`	`date` → `2026-07-12`

The first row is the whole story. The same field type — "Datetime (with time zone)" — is stored as an absolute instant on PostgreSQL, but as a bare wall-clock value on MySQL. MySQL's DATETIME simply has nowhere to put the offset. Keep that in mind for the next experiment.

Measurement 2: change the server TZ, and your stored data changes meaning (MySQL)

On the MySQL setup, I wrote "2026-07-12 09:00" while the server ran with TZ=UTC. Then I changed the app container to TZ=Asia/Tokyo and restarted. Nothing else.

# Raw value in MySQL (not a single byte changed)
dt_tz: 2026-07-12 09:00:00

# What the API returns
with TZ=UTC        → "2026-07-12T09:00:00.000Z"   (= 18:00 at UTC+9)
with TZ=Asia/Tokyo → "2026-07-12T00:00:00.000Z"   (= 09:00 at UTC+9)

The data on disk is byte-for-byte identical, but its meaning as an absolute instant moved by 9 hours. Because MySQL's DATETIME doesn't record which timezone's 09:00 this is, NocoBase has to interpret it through the server's TZ on every read and write. Change TZ after the fact, and every stored datetime in your database silently shifts meaning at once.

This mechanism explains most of the recurring "8-hour shift" reports: an instance starts life with TZ unset (= UTC), someone later sets it to local time — or staging and production simply disagree on TZ. No data was harmed; every interpretation was.

And PostgreSQL? I ran the same experiment and the values didn't move. timestamptz stored the offset, so there's nothing left to reinterpret.

Two rules fall straight out of this:

Pick the server TZ on day one and never change it — especially on MySQL. Pin it explicitly in your compose file, and keep it identical across environments (dev, staging, prod).
If you get to choose the database, PostgreSQL is structurally immune to this entire class of accident.

A separate thing: the import date bug (real, and fixed)

Not every shifted date is this mechanism. There was also a genuine bug in the 2.x era: on v2.0.44–2.0.51, CSV/Excel imports could store dates as one day earlier, even with database, app, and server timezones all aligned. It was confirmed as a defect and fixed in mid-May 2026 (forum threads t/12426, t/12494).

For what it's worth, I could not reproduce it on 2.0.51 importing xlsx/CSV through the API — both databases stored the dates correctly. The reports involved the UI path, so another route or environmental factor was likely involved. Either way, current versions have the fix.

The practical lesson: when dates shift, separate "is this the mechanism?" from "is this a known bug on my version?" Understanding measurement 1 and 2 covers the first question; a quick forum search (including the Chinese category — it's the most active by far) covers the second.

Checklist

Match the field type to the meaning. Birthdays and due dates belong in "Date only". Absolute instants belong in "Datetime (with TZ)". Using "Datetime (with TZ)" for date-only data is the classic way to get dates that render one day off.
Pin the server TZ in your compose file on day one and never touch it afterwards (MySQL especially). UTC or your local zone — either works; just pick one and use it everywhere.
After any import, open one record and check the datetime. These shifts hit every row uniformly — one record tells you everything.
If something is off: check your version, then search the forum — including the Chinese-language category, where most of the real-world reports live.

Takeaways

NocoBase 2.x "Datetime (with time zone)" is an absolute instant on PostgreSQL but a wall-clock value + TZ-based interpretation on MySQL (measured).
Which is why changing the server TZ later shifts the meaning of all stored datetimes on MySQL — the origin of the recurring "8-hour shift" (or 9, or whatever your offset is).
The import date-off-by-one bug was real but is fixed; distinguish mechanism from known bugs and the diagnosis gets fast.

(Measured on 2.0.51 / 2.1.23 × PostgreSQL 16 / MySQL 8.4. Behavior may change in future versions.)

References

Are NocoBase 2.x workflows really "sequential"? I measured it, and everything ran in parallel

stale_orbit — Tue, 21 Jul 2026 09:33:23 +0000

If you read the NocoBase workflow docs the way I did, you come away thinking workflows can't run concurrently. Two sentences do most of the damage:

Workflows can be triggered concurrently, but they are executed sequentially in a queue. Even if multiple workflows are triggered at the same time, they will be executed one by one, not in parallel.
— Executions

Regardless of the mode, each branch will be executed in order from left to right.
— Parallel branch

Taken at face value, that reads as "workflows have no throughput parallelism, and even parallel branches run one after another." If it were true, it would be a serious constraint on how you design anything with real load.

So I built the three scenarios on my own instance and measured them. My prediction was wrong three times in a row. The short version: everything runs in parallel, cleanly.

Test setup: NocoBase 2.1.23 (official Docker image) + PostgreSQL 16, on a 12-core machine. Workflows were created, triggered, and measured entirely through the REST API. Elapsed time is the difference between createdAt and updatedAt on rows in the executions table — not a stopwatch.

Test 1: two "wait 5 seconds" branches under a parallel node

I put a Parallel branch node in front of two branches, each with a single 5-second delay node.

Sequential → 10 s
Parallel → 5 s

Result:

status = 1 (success) / elapsed 5.17 s

5 seconds. The two waits overlapped in real time. Looking at the job records, the two delay nodes started 11 ms apart:

parallel branch   created = 06:25:01.894
delay A (5s)      created = 06:25:01.904
delay B (5s)      created = 06:25:01.915   <- did not wait for branch A to finish

So "executed in order from left to right" is about the order branches are entered, not the order they finish. The moment branch A parks itself on a wait, the engine hands control back and branch B starts. The waits stack.

Test 2: surely CPU work runs sequentially?

Fine, waits overlap. But Node.js is single-threaded, so CPU-bound work shouldn't overlap — that was my next assumption. I put a JavaScript node running a 3-second busy loop on each of two branches.

const t = Date.now();
while (Date.now() - t < 3000) {}  // hog the CPU for 3 seconds
return 'done';

Sequential → 6 s
Parallel → 3 s

Result:

status = 1 (success) / elapsed 3.18 s
both branches returned result = 'done'

3 seconds again. Even CPU work overlapped.

The trick is in the plugin. The JavaScript node doesn't run on the main event loop — it runs in a worker_threads worker:

// from @nocobase/plugin-workflow-javascript
var import_node_worker_threads = require("node:worker_threads");

Because it runs on a separate thread, a CPU-bound script doesn't block the main loop. "It's Node, so it's single-threaded" was exactly the wrong intuition here.

Test 3: fire four executions at the same time

This is the one the docs speak to most directly: "even if multiple workflows are triggered at the same time, they will be executed one by one."

I triggered the same 3-second-CPU workflow four times simultaneously.

Sequential → 12 s
Parallel → 3 s

Result:

 id   | status |   started    |   finished   | elapsed
------+--------+--------------+--------------+---------
 ...2 |      1 | 15:38:53.341 | 15:38:56.834 |  3.493
 ...3 |      1 | 15:38:53.395 | 15:38:56.782 |  3.387
 ...4 |      1 | 15:38:53.404 | 15:38:56.811 |  3.407
 ...5 |      1 | 15:38:53.408 | 15:38:56.823 |  3.415

wall-clock for all four: 3.49 s

All four ran fully in parallel. They started within ~70 ms of each other and finished within ~50 ms of each other. (Three 5-second delay executions fired together came in at 5.1 s wall-clock, same story.)

So are the docs wrong?

No — and this is the part worth slowing down on. The same Executions page also says, in effect: a "Running" execution that is parked on a waiting node is not holding the dispatch slot. Other queued executions can start while it waits.

In other words, "sequential" describes the order the dispatcher pulls from the queue, not "only one runs at a time." As soon as an execution hits a node that yields — a delay, a manual approval, an HTTP request — the next one starts. And JavaScript nodes escape to a worker thread entirely.

But I'll say this plainly: the English phrasing "one by one, not in parallel" reads as a throughput claim, and it made me design around a limit that isn't there. I misread it completely. Worth knowing: the Chinese-forum reports about "the queue getting stuck" (e.g. t/10331) are all from the 1.x era. In 2.x the dispatcher was reworked — PR #9673 fixed duplicate dispatch, PR #9953 eased lock contention — and it just runs concurrently.

Bottom line: you don't need to worry about 2.x workflow concurrency. Waits overlap, CPU work overlaps, simultaneous triggers overlap.

The real traps are somewhere else

Concurrency turned out to be a non-issue. But there are constraints that do bite in production — and the docs state them outright. These matter far more than the parallelism question.

1. Bulk operations don't fire events

"Collection events do not currently support triggering by bulk data operations."
— Collection event

And:

"using the SQL action node to operate on the database is equivalent to direct database operations and will not trigger collection events."

A workflow you thought you wired up silently does nothing depending on the path that changed the data. CSV bulk import or an update via the SQL node won't trigger it. If you put business logic in workflows, this is the biggest footgun.

2. Missed schedules never recover

"if ... the entire NocoBase application service is in an inactive or shutdown state, the scheduled task ... will be missed. Moreover, after the service is restarted, the missed tasks will not be triggered again."
— Schedule event

Any scheduled run that lands during a deploy or upgrade restart is silently dropped — and never replayed. If a daily batch lives in a workflow, mind your restart windows.

3. Loop limit defaults to unlimited

You can cap it with the WORKFLOW_LOOP_LIMIT env var, but the default is unlimited (Loop node). Get a loop condition wrong and nothing stops it. Set this in production.

4. No failure notifications

To a forum question — "my scheduled workflow errors out sometimes, there's no alert, and I only find out by digging through the history" — the official reply was:

"你好，目前没有" (currently, there is none)
— forum t/12040

Put something critical in a workflow and it can fail quietly. You have to build the monitoring yourself.

5. The transaction node arrived in 2.2.0

The DB transaction node — the one that rolls back a group of operations together — was added in 2.2.0 (Transaction node).

Which means 2.0 / 2.1 workflows have no all-or-nothing guarantee. Take a workflow that "① decrements stock → ② writes a shipment record." If ② fails, ① stays applied. Stock went down, no record exists — data left in a half-broken state. If you're running anything where integrity is the whole point (money, inventory) on 2.1 or earlier, keep this in mind.

Takeaways

Concurrency was never the problem (measured on 2.1.23). Parallel branches, and multiple simultaneously-triggered executions, overlap cleanly — for both waits and CPU work. JavaScript nodes run on worker_threads, so the single-thread intuition doesn't apply.
The official "sequentially in a queue / one by one, not in parallel" is about dispatch order. Read as a throughput claim, it misleads. (It misled me.)
The Chinese-forum "queue gets stuck" reports are all 1.x. The 2.x dispatcher was rebuilt.
The real traps are "won't fire / won't notice / breaks halfway" — bulk ops and the SQL node skip events, schedules are dropped on restart, failures are silent, and pre-2.2 has no transaction node so a mid-workflow failure leaves data inconsistent.

Reading one sentence of docs and designing around it cost me more than spinning up Docker and measuring would have. The environment is one docker compose up away — if something about your workflow design worries you, measure it.

(Measured on 2.1.23 / PostgreSQL 16 / 12 cores. Worker-thread count tracks CPU cores, so on a small box the CPU-parallelism will be lower.)