DEV Community: Muhammad Adnan

Your GraphQL API has two error modes: leaking Postgres internals, or "Internal server error"

Muhammad Adnan — Thu, 29 Oct 2026 22:10:03 +0000

Try this on your GraphQL API: sign up twice with the same email.

On a lot of TypeScript + Postgres backends you get one of two responses.

Mode 1: the leak.

{
"errors": [{
"message": "duplicate key value violates unique constraint \"users_email_key\"",
"extensions": { "code": "INTERNAL_SERVER_ERROR" }
}],
"data": null
}

Your table name, your constraint name, and a hint about your schema, sent to anyone who asks. And the client still can't act on it, because the code says "internal server error" for what is really "that email is taken".

Mode 2: the mask. Someone noticed Mode 1 and added a formatError that replaces every message with "Internal server error". Now nothing leaks, but the signup form shows "Something went wrong" for a duplicate email, an invalid input, a missing record and an actual outage alike. Your error dashboards can't tell them apart either.

Both modes have the same root cause: the resolver never decided which failures are expected (the user can fix them) and which are unexpected (you need to fix them).

The fix: two kinds of errors, decided in one place

1. Give expected failures a type and a stable code

import { GraphQLError } from "graphql";

export type ErrorCode =
| "BAD_USER_INPUT"
| "NOT_FOUND"
| "CONFLICT"
| "FORBIDDEN";

export class AppError extends GraphQLError {
constructor(code: ErrorCode, message: string, extra: Record<string, unknown> = {}) {
super(message, { extensions: { code, ...extra } });
}
}

The message is written for a human. The code is the contract: clients switch on it, and it never changes when you reword the message.

2. Translate database errors at the data layer, not in every resolver

Postgres already tells you exactly what went wrong through SQLSTATE codes. Translate the handful you expect, once:

const PG_UNIQUE_VIOLATION = "23505";
const PG_FOREIGN_KEY_VIOLATION = "23503";

export function translatePgError(err: unknown): never {
const e = err as { code?: string; constraint?: string };
if (e.code === PG_UNIQUE_VIOLATION) {
// Map constraint names to fields. Unknown constraints stay unexpected.
const field = UNIQUE_FIELDS[e.constraint ?? ""];
if (field) throw new AppError("CONFLICT", `That ${field} is already in use.`, { field });
}
if (e.code === PG_FOREIGN_KEY_VIOLATION) {
throw new AppError("BAD_USER_INPUT", "A referenced record does not exist.");
}
throw err; // everything else is a bug or an outage
}

const UNIQUE_FIELDS: Record<string, string> = {
users_email_key: "email",
orgs_slug_key: "slug",
};

async function createUser(db: Pool, input: { email: string }) {
try {
const { rows } = await db.query(
"insert into users (email) values ($1) returning *",
[input.email],
);
return rows[0];
} catch (err) {
translatePgError(err);
}
}

Note what this is not: it is not "check whether the email exists, then insert". That pattern has a race between the check and the insert. Let the unique constraint do the work and translate its error.

3. Mask only what you didn't expect

Now formatError has an easy job: pass AppErrors through untouched, mask everything else, and log the original with an id the client can quote.

import { randomUUID } from "node:crypto";
import { unwrapResolverError } from "@apollo/server/errors";

formatError(formatted, error) {
const original = unwrapResolverError(error);
if (original instanceof AppError) return formatted;
// GraphQL validation/parse errors are also safe to return as-is
if (formatted.extensions?.code && formatted.extensions.code !== "INTERNAL_SERVER_ERROR") {
return formatted;
}
const errorId = randomUUID();
logger.error({ err: original, errorId }, "unexpected resolver error");
return { message: "Internal server error", extensions: { code: "INTERNAL_SERVER_ERROR", errorId } };
}

The same idea works in GraphQL Yoga through its maskedErrors option.

4. Test it like a contract

The test that would have caught both modes is one line of intent: "a duplicate email returns CONFLICT on the email field, and the response does not mention the constraint name."

it("returns CONFLICT for a duplicate email without leaking schema names", async () => {
await signUp({ email: "a@example.com" });
const res = await signUp({ email: "a@example.com" });

expect(res.errors?.[0].extensions?.code).toBe("CONFLICT");
expect(res.errors?.[0].extensions?.field).toBe("email");
expect(JSON.stringify(res)).not.toContain("users_email_key");
});

I'm packaging patterns like this as Claude Code skills for TypeScript + GraphQL + Postgres backends, all tested against a real backend in CI. Two are free on GitHub.

Your cursor pagination is probably losing rows (JS Dates vs Postgres microseconds)

Muhammad Adnan — Wed, 28 Oct 2026 21:46:01 +0000

Keyset (cursor) pagination is the standard fix for slow OFFSET queries. You sort by created_at plus id, encode the last row into a cursor, and ask for "rows older than this" on the next page.

There's a bug in the most common way people build that cursor in Node, and it doesn't fail loudly. Rows just quietly go missing. In the worst case, pagination ends after the first page.

The usual implementation

const { rows } = await db.query(
  `SELECT * FROM events
    WHERE ($2::timestamptz IS NULL OR (created_at, id) < ($2::timestamptz, $3))
    ORDER BY created_at DESC, id DESC
    LIMIT $1`,
  [first + 1, afterTs, afterId],
);

const last = rows[first - 1];
const endCursor = Buffer.from(`${last.created_at.toISOString()}|${last.id}`).toString('base64url');

It looks right. There's a tiebreaker on id, the sort direction matches the comparison, and the cursor is opaque. It passes a quick manual test.

The problem

Postgres timestamptz stores microseconds. node-postgres parses it into a JavaScript Date, which stores milliseconds.

new Date('2026-10-29 02:30:24.156216+05').toISOString()
// '2026-10-28T21:30:24.156Z'   <- the 216 microseconds are gone

So the cursor says …24.156, but the row it came from is at …24.156216. That row, and every other row inside the same millisecond, is now newer than the cursor. The next page asks for rows older than …24.156 and skips all of them.

How bad it gets

If rows land in different milliseconds, you lose the occasional row: annoying, and very hard to notice. But look at what happens with a normal batch insert, where every row gets the same now() because now() is fixed for the whole transaction:

CREATE TABLE events (
  id bigserial PRIMARY KEY,
  created_at timestamptz NOT NULL DEFAULT now(),
  title text
);

BEGIN;
INSERT INTO events (title) SELECT 'event ' || g FROM generate_series(1, 10) g;
COMMIT;

All 10 rows have created_at = 2026-10-29 02:30:24.156216+05. Page 1 (LIMIT 3) returns ids 10, 9 and 8. Now page 2:

-- cursor built from a JS Date (millisecond precision)
SELECT count(*) FROM events
 WHERE (created_at, id) < (date_trunc('milliseconds', '2026-10-29 02:30:24.156216+05'::timestamptz), 8);
-- 0

-- cursor built from the exact Postgres value
SELECT count(*) FROM events
 WHERE (created_at, id) < ('2026-10-29 02:30:24.156216+05'::timestamptz, 8);
-- 7

Zero rows. The client sees an empty page with hasNextPage: false, and 7 of the 10 events are unreachable. No error, nothing in the logs.

Imports, seed scripts, fan-out jobs that create a notification for every user: anything that writes many rows in one transaction triggers it.

The fix

Never round-trip the timestamp through a JS Date. Ask Postgres for the exact text and put that in the cursor:

const { rows } = await db.query(
  `SELECT *, created_at::text AS cursor_ts
     FROM events
    WHERE ($2::timestamptz IS NULL OR (created_at, id) < ($2::timestamptz, $3))
    ORDER BY created_at DESC, id DESC
    LIMIT $1`,
  [first + 1, afterTs, afterId],
);

const encodeCursor = (r: { cursor_ts: string; id: string }) =>
  Buffer.from(`${r.cursor_ts}|${r.id}`).toString('base64url');

created_at::text keeps full precision and casts back to the identical timestamptz, so the comparison is exact.

Other options, depending on your setup:

Make the column millisecond precision: timestamptz(3). Rows in the same millisecond will then tie, so the id tiebreaker handles it correctly. This needs a migration on an existing table.
Paginate on id alone if ids are monotonic (bigserial, UUIDv7) and "newest first" by id is acceptable.
Parse timestamps as strings in node-postgres (types.setTypeParser(1184, v => v)). This works, but it changes the type everywhere, which is a bigger change than it looks.

Catch it with a test

This is the test that found it for me. Insert more rows than one page, walk every page, and check nothing is missing or repeated:

it('pages through every row exactly once', async () => {
  for (let n = 1; n <= 5; n++) {
    await db.query('INSERT INTO events (title) VALUES ($1)', [`event ${n}`]);
  }

  const seen: string[] = [];
  let after: string | null = null;
  do {
    const page = await listEvents({ first: 2, after });
    seen.push(...page.nodes.map((n) => n.title));
    after = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
  } while (after);

  expect(seen).toHaveLength(5);
  expect(new Set(seen).size).toBe(5);
});

Against a real Postgres, this failed for me with only 3 of 5 rows returned, even though every insert was a separate statement. Inserts that run quickly one after another regularly land in the same millisecond. A mocked database would never have caught it, because the mock would happily keep millisecond timestamps.

Checklist for keyset pagination

Sort by your field plus a unique tiebreaker (created_at DESC, id DESC)
An index that matches that exact order: (filter_col, created_at DESC, id DESC)
A cursor that holds the exact database value, not a JS Date
first capped (100 is typical) and invalid cursors rejected as a client error, not a 500
A test that walks every page against a real database

I hit this while building a set of Claude Code skills for TypeScript + GraphQL + Postgres backends, tested against a real starter backend in CI. The pagination skill now bakes this fix in, so Claude writes it correctly the first time. Two of the skills are free on GitHub.