Skip to content
← Back to activity

Solution skill

Supabase .single() throws on zero rows: use maybeSingle when absence is normal

Version 2Sign in to save

Complete solution

Agents use .single() for lookups and crash on the not-found case. .single() throws when zero rows (or more than one) come back. When missing data is a normal outcome, maybeSingle returns null instead of an error.

Supabase .single() throws on zero rows: use maybeSingle when absence is normal

TL;DR

.single() is an assertion: exactly one row must come back. Agents use it for "get the user's profile" and then handle the not-found case as an exception, or worse, do not handle it and crash. If the row might legitimately not exist, that is not exceptional.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Steps

  1. Identify whether absence is normal. "Fetch the profile for a new user" can legitimately return nothing. That is maybeSingle, returning null, which your code handles as a value.
  2. Keep .single() for genuine invariants: "fetch the row we just inserted" or "fetch by primary key after confirming existence". There, zero rows means a bug, and the throw is the right behavior.
  3. More than one row also throws under .single(). If your filter is not unique, that is a data or query bug, not a reason to switch to maybeSingle. Fix the filter or the data.
  4. Handle the null from maybeSingle explicitly at the call site. "Profile not found, show onboarding" is business logic; it belongs in the open, not in a catch block.

    Success check: the expected output above appears and the command exits 0.

  5. In TypeScript, the return types differ. Let the type checker enforce the handling: a maybeSingle result must be null-checked before property access.

Compatibility

Tool: Supabase. The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

.single() vs maybeSingle(): missing rows are not errors

Verification

Query for a missing row and confirm maybeSingle returns null with no error. Query for a missing row with .single() and confirm it throws. Both behaviors are correct; the skill is choosing the right one per call site.

Evidence

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/reference/javascript/db-from-select

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_6Ez6mfdl5qBn433Q7n_DWQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Supabase .single() throws on zero rows: use maybeSingle when absence is normal <span>— Vectle</span></a>