This guide handles the errors that the Neki router returns for statement shapes it does not implement yet. These errors carry SQLSTATE NK013 and a numeric code in square brackets, and the published Neki error codes page says what each code means and what to do instead. The guide writes a small wrapper that recognizes the code in an error, tells a not-implemented error apart from other failures, and shows the HINT when there is one.
What you will build
classify.sh "<statement>"
runs the statement with psql -v VERBOSITY=verbose
ERROR: NK013: not implemented: [49] ... -> prints the code, the message and a rewrite from the error codes page, exits 3
ERROR: NK017: ... HINT: ... -> prints the hint, exits 4
any other error -> prints the SQLSTATE and message, exits 1
AI Prompt
Using the PlanetScale CLI (pscale 0.344.0) and psql, handle Neki not-implemented errors in an application script.
Requirements:
- Create the Neki database with --engine neki, --cluster-size PS-10-AWS-ARM-NEKI and --replicas 2, add two shards, and wait until every shard answers a direct SELECT 1 with SET __neki.shard. Use one database role for every step.
- Shard orders by order_id with {"type":"xxhash","columns":["order_id"]}. Create an unsharded order_copy table as the target of one of the examples.
- Write classify.sh, which runs one statement with psql -X -At -v VERBOSITY=verbose, reads the SQLSTATE and the bracketed code from the first error line, and prints the rewrite for the code. Treat SQLSTATE NK013 as "not implemented, rewrite the statement" and never retry it.
- Run these statements through it: COPY (SELECT ...) TO STDOUT, INSERT ... SELECT ... ON CONFLICT DO UPDATE into an unsharded table, COMMIT AND CHAIN, PREPARE TRANSACTION, SET __neki.tx_mode = 'atomic', and DELETE ... USING with a now() expression in the join predicate.
- Show that a plain EXPLAIN of a router-processed query fails with SQLSTATE NK017 and a HINT, and that VERBOSITY=terse hides the HINT.
- Run the verification step below before finishing.
Prerequisites
A PlanetScale organization with access to the Neki Platform Preview. Create an account if you do not have one, and see Neki availability and access for how an organization administrator joins the preview.
pscale0.344.0 with a service token that can create databases,psql18.6,jq, andpython3:
export PLANETSCALE_SERVICE_TOKEN_ID="<token id>"
export PLANETSCALE_SERVICE_TOKEN="<token>"
export PLANETSCALE_ORG="<organization name>"
pscale version
- A Neki database with three shards. Create it with these commands:
pscale database create errdb --engine neki --org "$PLANETSCALE_ORG" \
--region us-east --cluster-size PS-10-AWS-ARM-NEKI --replicas 2 --wait
pscale role create errdb main admin --inherited-roles postgres --org "$PLANETSCALE_ORG" --format json > role.json
export PGHOST=$(jq -r .access_host_url role.json) PGUSER=$(jq -r .username role.json) \
PGPASSWORD=$(jq -r .password role.json) PGPORT=5432 PGDATABASE=postgres PGSSLMODE=require
rm role.json
until psql -At -c "SELECT 1" >/dev/null 2>&1; do sleep 5; done
pscale branch shard create errdb main --config-profile default --count 2 --org "$PLANETSCALE_ORG"
until [ "$(psql -At -c 'SELECT count(*) FROM __neki.list_shards()')" = "3" ]; do sleep 10; done
for u in $(psql -At -c "SELECT uid FROM __neki.list_shards()"); do
until psql -At -c "SET __neki.shard='$u';" -c "SELECT 1" >/dev/null 2>&1; do sleep 5; done
done
SHARD_1=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='sh1'")
SHARD_2=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='sh2'")
SHARD_3=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='sh3'")
Note: Output samples are trimmed to the relevant lines. Each shard bills as a three-node cluster.
PS-10-AWS-ARM-NEKIlists at $30 per month per shard, prorated to the millisecond. Current rates are on the Neki pricing page. Delete the database when you finish withpscale database delete errdb --force --org "$PLANETSCALE_ORG".
1. Create the tables
psql -q -v ON_ERROR_STOP=1 \
-c "CREATE TABLE orders (order_id bigint PRIMARY KEY, customer_id bigint NOT NULL, status text NOT NULL, total_cents int NOT NULL, placed_at timestamptz NOT NULL)" \
-c "CREATE TABLE order_copy (order_id bigint PRIMARY KEY, customer_id bigint, status text, total_cents int, placed_at timestamptz)" \
2>&1 | grep -v NOTICE
cat > data-topology.json <<JSON
{
"shard_indexes": { "order": { "type": "xxhash", "columns": ["order_id"] } },
"shard_groups": [
{ "uid": "$SHARD_1", "key_ranges": [ { "shard_uid": "$SHARD_1" } ] },
{ "uid": "by_order", "default_shard_index": "order",
"key_ranges": [ { "shard_uid": "$SHARD_2", "end": "80" }, { "shard_uid": "$SHARD_3", "start": "80" } ] }
],
"databases": { "postgres": { "schemas": { "public": { "tables": {
"orders": { "shard_group": "by_order" }
} } } } },
"default_shard_group": "$SHARD_1",
"authoritative_shard_group": "$SHARD_1"
}
JSON
pscale branch data-topology update errdb main --org "$PLANETSCALE_ORG" --format json < data-topology.json | jq -r '.status // "applied"'
sleep 10
psql -q -c "INSERT INTO orders SELECT i, i % 50, 'paid', 1000 + i, timestamptz '2026-10-01' + i * interval '1 minute' FROM generate_series(1, 100) i"
psql -At -c "SELECT count(*) FROM orders"
Real output:
applied
100
orders is sharded by order_id. order_copy is not in the topology, so it is an unsharded table on the authoritative shard.
2. Write the wrapper
cat > classify.sh <<'EOF'
#!/bin/bash
# classify.sh "<statement>": run one statement and explain a failure
out=$(psql -X -At -v VERBOSITY=verbose -c "$1" 2>&1 | grep -vE '^(CONTEXT|LOCATION):')
line=$(echo "$out" | grep -m1 '^ERROR:')
if [ -z "$line" ]; then echo "ok: $(echo "$out" | head -1)"; exit 0; fi
state=$(echo "$line" | sed -E 's/^ERROR: +([A-Z0-9]{5}):.*/\1/')
hint=$(echo "$out" | sed -n 's/^HINT: *//p' | head -1)
code=$(echo "$line" | sed -nE 's/.*not implemented: \[([0-9]+)\].*/\1/p')
if [ "$state" = "NK013" ]; then
case "$code" in
22|23|26) fix="use plain BEGIN, COMMIT and ROLLBACK, and the tx_mode values single or multi" ;;
49) fix="copy the whole table, or run the query with psql --csv" ;;
103) fix="remove the router-only expression (such as now()) from the join predicate, or compute it in a first query" ;;
117) fix="insert explicit VALUES, or drop the DO UPDATE" ;;
*) fix="look up code $code on the Neki error codes page" ;;
esac
echo "NK013 [$code] not implemented -> $fix"; exit 3
fi
if [ -n "$hint" ]; then echo "$state ${line#*: *: } | hint: $hint"; exit 4; fi
echo "$state ${line#*: *: }"; exit 1
EOF
chmod +x classify.sh
./classify.sh "SELECT count(*) FROM orders"
Real output:
ok: 100
A statement that works prints ok: and its first output line. The script reads the SQLSTATE from the first ERROR: line, the bracketed number after not implemented:, and any HINT: line.
3. Run statements that the router does not implement
for q in \
"COPY (SELECT order_id FROM orders) TO STDOUT" \
"INSERT INTO order_copy SELECT * FROM orders ON CONFLICT (order_id) DO UPDATE SET status = excluded.status" \
"COMMIT AND CHAIN" \
"PREPARE TRANSACTION 'x'" \
"SET __neki.tx_mode = 'atomic'" \
"DELETE FROM orders USING order_copy c WHERE orders.placed_at < c.placed_at + (extract(epoch from now()) || ' seconds')::interval"
do
./classify.sh "$q"; echo " exit=$?"
done
Real output:
NK013 [49] not implemented -> copy the whole table, or run the query with psql --csv
exit=3
NK013 [117] not implemented -> insert explicit VALUES, or drop the DO UPDATE
exit=3
NK013 [22] not implemented -> use plain BEGIN, COMMIT and ROLLBACK, and the tx_mode values single or multi
exit=3
NK013 [23] not implemented -> use plain BEGIN, COMMIT and ROLLBACK, and the tx_mode values single or multi
exit=3
NK013 [26] not implemented -> use plain BEGIN, COMMIT and ROLLBACK, and the tx_mode values single or multi
exit=3
NK013 [103] not implemented -> remove the router-only expression (such as now()) from the join predicate, or compute it in a first query
exit=3
Each of these failed with SQLSTATE NK013 and a different code, and the script exited with 3 for every one. The messages in this build are worded differently from the examples on the error codes page for some codes, so match on the bracketed code and not on the text.
4. Hints and other errors
./classify.sh "EXPLAIN SELECT order_id FROM orders ORDER BY order_id"; echo " exit=$?"
./classify.sh "SELECT unknown_fn(1)"; echo " exit=$?"
./classify.sh "INSERT INTO orders VALUES (1, 1, 'paid', 1, now())"; echo " exit=$?"
echo "-- the same EXPLAIN with VERBOSITY=terse:"
psql -X -At -v VERBOSITY=terse -c "EXPLAIN SELECT order_id FROM orders ORDER BY order_id" 2>&1
echo "-- the plan the hint asks for:"
psql -X -At -c "EXPLAIN (NEKI_PG_PLAN, COSTS OFF) SELECT order_id FROM orders ORDER BY order_id" 2>&1 | head -3
Real output:
NK017 This statement requires Neki router processing | hint: Use `EXPLAIN (NEKI_PG_PLAN)` (with ANALYZE to execute) to see Neki's plan
exit=4
42883 function unknown_fn(integer) does not exist | hint: No function matches the given name and argument types. You might need to add explicit type casts.
exit=4
23505 duplicate key value violates unique constraint "orders_pkey"
exit=1
-- the same EXPLAIN with VERBOSITY=terse:
ERROR: This statement requires Neki router processing
-- the plan the hint asks for:
Sort [Merge]
-> Route [Scatter]
Query: SELECT order_id FROM public.orders ORDER BY 1
A plain EXPLAIN of a query that needs router processing fails with SQLSTATE NK017, which is a different error from NK013, and its HINT names the option to use. Postgres errors keep their own SQLSTATE, and their HINT when they have one: the unknown function has a hint and the duplicate key does not. With VERBOSITY=terse the HINT is gone, so the wrapper keeps the default verbosity.
Verify the result
for q in "COPY (SELECT order_id FROM orders) TO STDOUT" "COMMIT AND CHAIN" "SELECT count(*) FROM orders"; do ./classify.sh "$q" >/dev/null; echo -n "$? "; done; echo
Expected: 3 3 0. Two not-implemented statements exit 3 and a working statement exits 0.
How it works
When the router has no implementation for a statement shape, it returns SQLSTATE NK013 and a message of the form not implemented: [<code>] <text>. The published catalog says each code is stable and is never reused for a different gap, so the code is the thing to match in an application, and the text can change. A rejection often has no HINT, which the error hints and details page says, so the wrapper carries its own rewrite for each code it knows and falls back to the catalog. Errors that a shard's Postgres raises keep their SQLSTATE, message and HINT.
Common issues
Do not retry NK013
A not-implemented error is a property of the statement. Running it again gives the same error. Rewrite the statement as the error codes page says, and log the code with the statement so it can be found later.
The message text is not the code
The [117] message in step 3 mentions an unsharded table, and the error codes page shows a different sentence for the same code. Match the number.
Terse error output hides hints
With VERBOSITY=terse the HINT line was not printed for the NK017 error. Keep the default verbosity in tools and application logging for Neki, and log the SQLSTATE, DETAIL and HINT as well as the message.
One statement can show several codes
The error codes page notes that a statement can hit more than one gap and that you see the first one the planner reaches. After rewriting for one code, run the statement again.
Next steps
- Delete the database with
pscale database delete errdb --force --org "$PLANETSCALE_ORG". - Read the guide on exporting a sharded table with
COPY TO STDOUTfor the[49]rewrite in full. - Read the Neki error codes page for the codes this guide does not cover.
verification:
status: verified
tested_at: "2026-10-29"
product_version: "pscale 0.344.0, Neki PostgreSQL 18.6 (Platform Preview)"
command: "classify.sh exit codes for two not-implemented statements and one working statement"
expected_result: "3 3 0"