Skip to main content

Troubleshooting

SyntaxError: … 'node:fs' does not provide an export named 'globSync'​

You are on a Node.js older than 22. The driver reads globSync from node:fs, which earlier runtimes do not export, so the failure happens at import time rather than at a call site.

Fix. Use Node 22 or newer everywhere — including CI runners and Docker images.

My @Index() did nothing​

Indexes are not created by discovery; they are created by orm.schema.ensureIndexes(). Call it at bootstrap — it is idempotent and emits IF NOT EXISTS for every statement.

ensureIndexes() also never drops: removing a declaration leaves the index in place. Drop it by hand with DROP INDEX <name>, which is also what changing an existing fulltext index's properties, weights or analyzer requires. See indexes.

ensureIndexes() fails on a composite uniqueness constraint​

Composite uniqueness constraints landed in Neo4j 5.7. They are a hard requirement of schema support, and the driver re-throws with the requirement spelled out rather than degrading to a non-unique index — which would leave identity unprotected while looking healthy.

My entities disappeared after adding schema​

Every query now filters on __schema, and nodes written before the change have none. Backfill them:

const generator = orm.schema as Neo4jSchemaGenerator;
await generator.assignDefaultSchema(Invoice);

It writes in batches, so it must not run inside em.transactional(). Details and the equivalent raw Cypher: migrating existing data.

Procedure not found: apoc.…​

APOC is a plugin, not part of the server. Start Neo4j with NEO4J_PLUGINS='["apoc"]', or declare a local fallback with bodyJs so the code path runs against a plain container. A fallback is never used when the routine is installed.

A filter operator throws by name​

Not every MikroORM operator has a Cypher meaning. $hasKey, $hasKeys and $hasSomeKeys have none at all — Neo4j properties hold primitives and lists, never maps — and the driver names the operator rather than quietly matching nothing. The full translation table is in query conditions.

A raw SQL fragment reached a filter​

Neo4jRawFragmentError: Raw SQL fragments are not supported by the Neo4j driver

Core's sql tag binds positionally; Bolt binds by name. Use the cypher tagged template instead — same ergonomics, named parameters.

Streaming is slow to produce the first entity​

An ORDER BY adds a blocking Sort: the server materializes and sorts the whole result before sending a record. Order by an indexed property or by the primary key so the planner takes the order from the index instead. See ordering, and what stays lazy.

Running workflows with act on Apple Silicon​

An M-series Mac may hit exit code 137 (OOM or an architecture crash) during setup-node.

act --container-architecture linux/amd64

Also give Docker Desktop 4–6 GB of RAM in Settings → Resources.