Intermittent RPC hang with lock: No-Op config (not covered by PR #2106)

[MartinJandri]

Bug Summary

supabase.rpc() calls hang indefinitely (~5–10% of calls) when createClient is configured with lock: async (_n, _t, fn) => fn() (No-Op lock for multi-tab scenarios). The Promise neither resolves nor rejects. PR #2106's steal: true retry fix doesn't apply because No-Op lock bypasses the navigator.locks code path entirely.

Environment

• @supabase/supabase-js 2.105.4 (latest stable as of 2026-05-08)
• @supabase/auth-js 2.105.4 (bundled, contains PR fix(auth): recover from orphaned navigator locks via steal fallback #2106 fix already)
• React 19.2.6
• Vite 8.0.12 (dev server, React Strict Mode off)
• Chrome 130+ on macOS 14
• Single tab, single authenticated user session (no multi-tab scenario at repro time)

Setup (relevant createClient config)

import { createClient } from '@supabase/supabase-js'

const FETCH_TIMEOUT_MS = 15000

const fetchWithTimeout: typeof fetch = (input, init) => {
  const controller = new AbortController()
  const timeoutId = setTimeout(
    () => controller.abort(new DOMException(`Timeout ${FETCH_TIMEOUT_MS}ms`, 'TimeoutError')),
    FETCH_TIMEOUT_MS
  )
  return fetch(input, { ...init, signal: controller.signal })
    .finally(() => clearTimeout(timeoutId))
}

export const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  auth: {
    // No-Op lock as a workaround for an earlier multi-tab navigator.locks hang
    // (orphaned-lock cluster). Replaces the default navigator.locks usage.
    lock: async (_name, _acquireTimeout, fn) => fn(),
  },
  global: {
    fetch: fetchWithTimeout,
  },
})

Reproduction steps

1. Use the config above.
2. Log in via supabase.auth.signInWithPassword(...).
3. Call any RPC repeatedly:

for (let i = 0; i < 20; i++) {
  const start = performance.now()
  const { data, error } = await supabase.rpc('your_rpc', { /* args */ })
  console.log(`call ${i}: ${(performance.now() - start).toFixed(0)}ms`, { data, error })
}

4. Observe: 1–2 of the 20 calls hang. They eventually error with our fetchWithTimeout's TimeoutError after 15s. Without the timeout wrapper, the Promise stays pending forever.

Expected behavior

All 20 RPC calls resolve with HTTP 200 within ~100ms each.

Actual behavior

5–10% of calls hang. They are not aborted by the client, they don't time out at the PostgREST layer (the request never reaches the server — see evidence below). Without an external timeout wrapper, they remain pending indefinitely.

Evidence — server is fine, client is the culprit

Equivalent direct fetch() (bypassing the SDK entirely, same auth token from localStorage['sb-<project-ref>-auth-token'], same endpoint, same headers):

const SUPABASE_URL = import.meta.env.VITE_SUPABASE_URL
const SUPABASE_KEY = import.meta.env.VITE_SUPABASE_ANON_KEY

function extractAccessToken(): string | null {
  for (const key of Object.keys(localStorage)) {
    if (key.startsWith('sb-') && key.endsWith('-auth-token')) {
      const parsed = JSON.parse(localStorage.getItem(key)!)
      return parsed?.access_token ?? null
    }
  }
  return null
}

async function directRpc<T>(rpcName: string, args: Record<string, unknown>): Promise<T> {
  const token = extractAccessToken()!
  const r = await fetch(`${SUPABASE_URL}/rest/v1/rpc/${rpcName}`, {
    method: 'POST',
    headers: {
      apikey: SUPABASE_KEY,
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(args),
  })
  if (!r.ok) throw new Error(`HTTP ${r.status}: ${await r.text()}`)
  return await r.json() as T
}

// Stress test:
for (let i = 0; i < 10; i++) {
  const start = performance.now()
  await directRpc<unknown>('your_rpc', { /* same args */ })
  console.log(`direct ${i}: ${(performance.now() - start).toFixed(0)}ms`)
}

Result on our environment: 10/10 HTTP 200, avg 93ms, max 322ms. Same RPC, same user, same session, same browser — no hangs.

Why this is NOT issue #2111 / fixed by PR #2106

#2111 describes orphaned navigator.locks leading to indefinite auth hangs. PR #2106 fixes that by retrying lock acquisition with { steal: true } after a 5s timeout.

Our config explicitly bypasses navigator.locks via lock: async (_n, _t, fn) => fn(). The steal: true retry path is never taken because the lock callback resolves immediately. We're hitting a different race.

Hypothesis

Without lock-based serialization, the auth-refresh background cycle (or some other internal queue) can interleave with concurrent RPC requests in a way that leaves a fetch in a non-resolvable state. PostgREST client internals (auth-token refresh handler? request queue?) seem to assume the lock semantics are present.

This is consistent with:

• Bug only manifests post-login (anonymous-only calls don't reproduce reliably for us).
• Bug rate is ~5–10%, suggesting timing-dependent race.
• Direct fetch (which bypasses the entire SDK's request pipeline) is 100% reliable.

Asks

1. Is lock: async (_n, _t, fn) => fn() (No-Op lock) a supported configuration? The TypeScript signature allows it, but if the SDK assumes lock semantics elsewhere, the No-Op breaks invariants.
2. If supported: is there a known race condition between the No-Op lock path and auth-refresh / request queueing that could leave fetches in a pending-forever state?
3. If not supported: what's the recommended pattern for opting out of multi-tab lock serialization without losing the SDK's request reliability? (Background: many internal-tool SPAs don't need cross-tab serialization but were hit by the original navigator.locks orphan cluster.)

Workaround currently in production

We bypass the SDK for the affected RPCs entirely (direct fetch() with manual token extraction). Plus a global fetchWithTimeout wrapper as a safety net for any other SDK call that might hang. Functional but introduces technical debt (duplicate request path, manual auth-storage parsing).

Happy to provide a minimal runnable StackBlitz repro if useful — let me know.

---

Filed from an internal SaaS team running supabase-js in a small React admin app — happy to dig deeper if useful.

[mandarini]

Hi @MartinJandri, thank you for opening this issue! The direct-fetch baseline makes it clear this is on us.

Quick answer on what to do today: your no-op lock config is supported (it matches the SDK's own lockNoOp fallback), but the hang lives one level up in _acquireLock's pendingInLock drain loop, not in the lock primitive. That is why bypassing navigator.locks does not help. Same root pattern as #2126, #2145, and #2344.

Workaround: pass an accessToken callback to createClient. It short-circuits _getAccessToken before auth.getSession() runs, so RPC/from/Storage/Functions calls stop going through _acquireLock entirely.

let cachedAccessToken: string | null = null

const supabase = createClient(URL, KEY, {
  accessToken: async () => cachedAccessToken,
})

const { data: { session } } = await supabase.auth.getSession()
cachedAccessToken = session?.access_token ?? null

supabase.auth.onAuthStateChange((_event, session) => {
  cachedAccessToken = session?.access_token ?? null
})

auth-js still owns sign-in, refresh, and persistence. If a refresh happens mid-request the in-flight call uses the previous token and may 401, so a single retry-on-401 wrapper is worth adding if you see them.

Path forward: we are shipping a lockless redesign of the auth client next month that removes _acquireLock / pendingInLock entirely. You can drop the accessToken workaround once it lands.

A minimal StackBlitz repro would still help us validate the rework against your exact scenario. I will tag you back here when it ships.

So please bear with us a bit longer!

[Owez]

@mandarini Do you know what version that lockless design will probably release on? I remember there was a version that reportedly patched so noop wasn't needed, but that didn't work for us so we had to revert back to using this noop workaround. Cheers

[mandarini]

Here is the refactor: #2392

Published under 2.107.0-beta.1.

Instructions on how to migrate are here.

Non breaking change, backwards compatible. Please let me know if you try it out, we're trying to evaluate this before publishing.

@MartinJandri @Owez