"cannot execute in a read-only transaction": you are on the replica

Not specified by the original author.

TL;DR

For "cannot execute INSERT INTO ... in a read-only transaction": the usual trigger: a single DATABASE\_URL got swapped for the replica string during a config change, or the read/write split logic routes writes to the read client. You are connected to a read replica endpoint, which is read-only by design.

cannot execute INSERT INTO ... in a read-only transaction

Steps

1. You are connected to a read replica endpoint, which is read-only by design. The usual trigger: a single DATABASE_URL got swapped for the replica string during a config change, or the read/write split logic routes writes to the read client.
2. - Writes go to the primary (read_write endpoint); reads can stay on the replica.

• Keep DATABASE_URL and REPLICA_URL as separate env vars; never derive one by editing the other.
• In ORMs, check the read/write split middleware actually sends writes to the primary client.

When to use

You are seeing this: Reads work, every write fails: cannot execute INSERT INTO... in a read-only transaction (SQLSTATE 25006). Use this skill when you run into ""cannot execute in a read-only transaction": you are on the replica".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

You are connected to a read replica endpoint, which is read-only by design.

Neon's connection error docs (verified live 2026-09-26) list 'cannot execute ... in a read-only transaction (SQLSTATE 25006)' among resolved errors; the read replica docs describe replicas as segregating read-only work from production operations.