Storage API returns 503 "The database schema is invalid or incompatible" on all authenticated operations (project byuoolwmzlqewncjlgzo

[anouguesdeelia-prod]

Since 2026-09-16 every authenticated Storage operation on my project fails:

StorageApiError — 503
"The database schema is invalid or incompatible."

Project ref: byuoolwmzlqewncjlgzo · Free plan · us-east-1
Client: supabase-js 2.105.1 / storage-js 2.108.0 (browser)

What fails

POST /object/avatares//avatar.jpg → 503 in ~40ms
POST /object/list/avatares → 400

All four buckets. Both new uploads and upserts. Also plain LIST calls —
listing a bucket should never fail, and it does not consume any quota, which
rules out plan limits. Storage usage is ~1 MB of a 1 GB allowance.

What still works

• Public reads: GET /object/public/... → 304, served normally
• PostgREST and Auth: completely unaffected
• Dashboard uploads: these go through @supabase-infra/mgmt-api, a different
  service, so they do not indicate storage-api is healthy

Timeline

storage.migrations shows these applied on 2026-09-16 21:13:

068 bucket-lifecycle-configuration
069 validate-bucket-lifecycle-constraints
070 list-objects-with-versions
071 objects-delete-marker-index
072 drop-bucketid-objname-index

The most recent object write in the whole project is 2026-09-07 23:00.
Nothing has been written since those migrations ran.

Schema state

All four rows in storage.buckets are well formed (type STANDARD,
versioning_status DISABLED, all columns populated). RLS policies exist per
bucket. A policy rejection would return "new row violates row-level security
policy", which is not what we get — and a 503 is not client-caused.

Already ruled out

• Project restart
• Postgres upgrade 17.6.1.111 → 17.6.1.166
• Legacy anon key AND new sb_publishable_ key (same error with both)
• Fresh sign-in / new session token
• Service worker interference (our SW does not intercept fetch)
• Plan limits (LIST fails too, and usage is ~0.1% of the allowance)

A support ticket was opened and has not been answered.

Ask

storage-api appears to be on a version incompatible with the migrated storage
schema for this project. Can someone check the storage-api version running for
byuoolwmzlqewncjlgzo and re-sync it?

[GaryAustin1]

This has occurred in the past and was an RLS policy.
Check your storage logs for details on the error.

Resolved on our side. Posting the root cause for anyone hitting this in the future.

Cause: a SELECT policy on a public table queried itself in its USING clause:

  CREATE POLICY ... ON group_chat_members FOR SELECT
  USING (EXISTS (SELECT 1 FROM group_chat_members m2 WHERE ...));

Postgres rewriter expands all permissive policies for the role at plan time, so even uploads to OTHER buckets that didn't logically need access to this table got killed during the rewrite phase with 42P17. Storage server caught it as "schema is invalid or incompatible" → returned 400 to the client.

Fix: replaced the self-referencing EXISTS with a SECURITY DEFINER helper function that bypasses RLS for the membership check. All buckets uploading correctly now.

[anouguesdeelia-prod]

UPDATE: uploads using the service_role key from a server route DO work.
Only requests authenticated with the anon / sb_publishable key are rejected
with 503 "The database schema is invalid or incompatible".

So storage-api is not failing on the schema — it is rejecting public
credentials specifically. The error message appears to be misleading.

[GaryAustin1]

Check the storage log and Postgres log around the time of the request to see if it is an RLS error. Remember ALL polices on storage.objects run (OR'd together) and not just any you have in the bucket policy UI (that is just for convenience).

[anouguesdeelia-prod]

That was the key, thank you — and it turned out to be our own bug.

You're right that ALL policies on storage.objects are evaluated (OR'd).
I had been looking only at the policy for the bucket I was uploading to.

What was happening:

One of our policies on storage.objects, for a private "chat-club" bucket,
does an EXISTS against an application table:

chatclubfile_ins · WITH CHECK (bucket_id = 'chat-club' AND EXISTS (
  SELECT 1 FROM chat_equipo_miembros m
  WHERE m.equipo_id::text = (storage.foldername(objects.name))[1]
    AND m.user_id = auth.uid()))

And that table had a self-referencing RLS policy:

SELECT · USING (EXISTS (
  SELECT 1 FROM chat_equipo_miembros m2
  WHERE m2.equipo_id = chat_equipo_miembros.equipo_id
    AND m2.user_id = auth.uid()))

Postgres reports that as 42P17 "infinite recursion detected in policy for
relation chat_equipo_miembros".

Because every policy on storage.objects runs, that recursion was hit on
EVERY upload, to EVERY bucket — not just chat-club. That is why uploads and
LIST failed project-wide while public reads and service_role writes were
fine: neither of those evaluates the policies.

The fix was to move the membership check into a SECURITY DEFINER function so
the inner query no longer re-enters the policy:

create function esta_en_chat_equipo(_equipo uuid) returns boolean
  language sql stable security definer as $$
    select exists (select 1 from chat_equipo_miembros m
                    where m.equipo_id = _equipo and m.user_id = auth.uid())
  $$;

create policy chateqm_sel on chat_equipo_miembros for select to authenticated
  using (esta_en_chat_equipo(equipo_id));

One suggestion, for whoever hits this next: storage-api surfaced it as

503 "The database schema is invalid or incompatible."

That message sent me looking at storage migrations and the storage schema for
two days. It would have saved a lot of time if the underlying Postgres error
(42P17) were surfaced, or at least if the message didn't point at the schema.

[somuai]

The fact that service_role requests succeed while anon / authenticated requests fail with 503 "The database schema is invalid or incompatible" is the definitive diagnostic key.

This is not a key validation failure, and the error message is not a random platform glitch. It is caused by an infinite recursion error in Row-Level Security (RLS) that Supabase Storage intercepts and maps to 503 DatabaseInvalidObjectDefinition.

---

Architectural Root Cause: Why service_role Succeeds and authenticated Returns 503

1. The PostgreSQL RLS Bypass Mechanism

In PostgreSQL, the service_role user possesses the BYPASSRLS role attribute:

ALTER ROLE service_role BYPASSRLS;

When requests arrive using the service_role secret, PostgreSQL bypasses all Row-Level Security policies on storage.objects. The query planner never expands or executes RLS expressions, allowing the query to complete without error.

2. The Query Rewriter Loop on authenticated / anon

When a request uses public client credentials (anon / sb_publishable_ plus a user JWT), the Storage API executes queries against storage.objects under the authenticated (or anon) PostgreSQL role.

PostgreSQL passes the query to its query rewriter to expand all active RLS policies on storage.objects. If any policy on storage.objects references another table (for example, checking membership in public.profiles or public.teams) and that referenced table has an RLS policy that references back to storage.objects (or recursively references itself via an unconstrained EXISTS subquery), PostgreSQL hits an infinite planning cycle and aborts with SQLSTATE 42P17 (infinite_recursion).

3. Why 42P17 Translates to HTTP 503

In the open-source Supabase Storage API (supabase/storage), database errors are processed in src/storage/database/errors.ts:

case '42P17':
  return ERRORS.InvalidObjectDefinition(pgError).withMetadata(
    pgErrorMetadata(pgError, context)
  )

And in src/internal/errors/codes.ts:

InvalidObjectDefinition: (e?: Error) =>
  new StorageBackendError({
    code: ErrorCode.DatabaseInvalidObjectDefinition,
    httpStatusCode: 503,
    message: 'The database schema is invalid or incompatible.',
    originalError: e,
  }),

When PostgreSQL throws 42P17 (infinite recursion detected in policy for relation ...), storage-api translates that specific database code directly into 503 DatabaseInvalidObjectDefinition with the message "The database schema is invalid or incompatible."

---

Step-by-Step Diagnostic Runbook

To pinpoint the exact policy and relation causing the recursion, execute the following steps in the Supabase Dashboard SQL Editor:

Step 1: Reproduce the Raw PostgreSQL Error

Simulate an authenticated user transaction inside the SQL Editor. This forces PostgreSQL to run the RLS query rewriter without executing changes:

BEGIN;
SET LOCAL ROLE authenticated;
SET LOCAL "request.jwt.claim.sub" = '00000000-0000-0000-0000-000000000000';

-- Execute a test select against storage.objects
SELECT id, name, bucket_id FROM storage.objects LIMIT 1;

ROLLBACK;

When this runs, PostgreSQL will output the exact unmasked error:

ERROR: 42P17: infinite recursion detected in policy for relation "<relation_name>"

The <relation_name> reported in the error message is the specific table where the circular policy resides.

Step 2: Inspect All Active Policies on storage.objects

List all policies attached to storage.objects to find which policy introduces the cross-table subquery:

SELECT
  policyname,
  permissive,
  roles,
  cmd,
  qual AS using_expression,
  with_check AS with_check_expression
FROM pg_policies
WHERE schemaname = 'storage' AND tablename = 'objects';

Look for any policy containing EXISTS (SELECT 1 FROM ...) or joins referencing public tables.

---

Permanent Remediation: Break Policy Recursion with SECURITY DEFINER

To fix the circular dependency, any cross-table check in an RLS policy must not trigger a secondary RLS evaluation loop.

1. Wrap the Permission Check in a SECURITY DEFINER Function

Create a secure function that runs with the privileges of the creator, bypassing RLS on the lookup table:

CREATE OR REPLACE FUNCTION public.can_access_avatar(bucket text, object_name text)
RETURNS boolean
LANGUAGE sql
SECURITY DEFINER
SET search_path = public, pg_temp
STABLE
AS $$
  SELECT EXISTS (
    -- Your specific ownership or membership logic here:
    SELECT 1 
    FROM public.profiles
    WHERE id = auth.uid()
      AND avatar_url = object_name
  );
$$;

2. Recreate the Storage RLS Policy

Update the policy on storage.objects to use the helper function instead of direct table queries:

-- Example for SELECT / download:
DROP POLICY IF EXISTS "Avatar access policy" ON storage.objects;

CREATE POLICY "Avatar access policy"
ON storage.objects
FOR SELECT
TO authenticated
USING (
  bucket_id = 'avatares' 
  AND public.can_access_avatar(bucket_id, name)
);

Once the recursive subquery is encapsulated in SECURITY DEFINER, the PostgreSQL query planner evaluates storage.objects without recursion, eliminating SQLSTATE 42P17, and authenticated Storage API requests will succeed immediately.