If your website works on Cloudflare Workers but its Supabase-backed routes return HTTP 500 after a migration, do not rebuild the application first. Separate the database connection method from the Worker runtime, inspect the actual exception, and reproduce one failing operation safely. A 500 is an outcome, not a diagnosis.
The key question is whether your Worker talks to Supabase’s HTTPS API through supabase-js, or connects directly to PostgreSQL through a driver such as pg, Postgres.js or an ORM. These paths need different fixes. Cloudflare’s official Supabase integration guide describes both.
For founders paying a developer to rescue a production MVP, the goal is not merely to make one request return 200. It is to restore login, data writes, permissions, payment state and repeatable deployments without introducing another outage.
First, identify which part actually fails
| Symptom | More useful question | First place to look |
|---|---|---|
| Static pages work; database API routes return 500 | Does the route use supabase-js or a direct SQL driver? |
Worker exception and route configuration |
| First request works, later requests hang | Is a database client or pool being reused across Worker requests? | Module-scope connections and request lifecycle |
| Hyperdrive reports a pool acquisition failure | Are queries or transactions holding connections too long? | Hyperdrive metrics and slow queries |
| Login works but a user cannot read their records | Is this an authorization or RLS error rather than a connection failure? | Supabase response and policies |
| Payments succeed but the dashboard shows old status | Could a cached read or incomplete reconciliation explain the mismatch? | Query caching and verified payment records |
Do not infer the root cause from this table alone. Record the endpoint, time, deployment version, error code and relevant stack trace. Keep tokens, passwords, connection strings and customer data out of shared logs and support screenshots.
Two connection paths that should not be confused
Path A: Supabase JavaScript client over HTTPS
The @supabase/supabase-js client talks to Supabase’s APIs over HTTP(S). It is appropriate when your app needs Supabase Auth, Storage, PostgREST and related platform features. Hyperdrive does not sit in front of those HTTPS API calls. Adding a Hyperdrive binding cannot repair a broken supabase-js request by itself.
If this is your path, check the production Supabase URL, keys, auth session propagation, CORS where applicable, RLS policies, API errors and recent environment changes. A missing Worker secret and a database connection limit are different incidents.
Cloudflare’s Supabase-on-Workers documentation shows the API-client approach separately from direct PostgreSQL access. Do not expose a Supabase secret or service-role key in browser code to make a permission error disappear.
Path B: Direct PostgreSQL through a Worker
If your Worker uses pg, Postgres.js, Drizzle or another SQL driver, inspect the connection string, driver compatibility and connection lifetime. Cloudflare recommends Hyperdrive for direct PostgreSQL connections, which pools database connections close to the origin.
The crucial Worker-specific rule is to create the database client inside the request handler and close it when finished. Cloudflare’s connection lifecycle guidance warns against keeping database clients or driver pools in global scope across requests. A connection created in one request context can become unusable in another.
This can surprise teams migrating from a persistent Node.js server. General serverless documentation may recommend reusing a small module-level pool in a long-lived process; Cloudflare Workers has different I/O context rules. Follow the guidance for the runtime actually executing your code.
Why adding Hyperdrive may not fix the 500
Hyperdrive is a connection and query layer, not an automatic repair service. A broken binding name, unsuitable driver, bad database endpoint, insufficient database permissions, a slow query or a connection held open can still fail.
Cloudflare’s Hyperdrive troubleshooting reference distinguishes a pool acquisition timeout from a refused origin connection, missing Node module and stale cross-request connection. Those are different remediation tasks.
Also confirm you are not layering connection pooling without understanding it. Supabase offers direct, session and transaction connection modes, each with different limitations. Its database connection documentation explains that transaction pooling does not support prepared statements in the same way as a persistent session. Choose the supported route for your driver and workload; do not blindly copy another application’s port number.
Before changing production credentials or connection modes, test in staging with a database user that has only the permissions needed. Keep a rollback route and a verified backup appropriate to the data at risk.
A safe repair sequence
1. Preserve the last working deployment
Record the last known good Worker version, environment configuration, database settings and migration changes. If real users are affected, consider rolling back the application while you investigate. A database schema change may make an old Worker incompatible, so verify the rollback rather than assuming it is safe.
2. Capture one representative failure
Use Worker logs and a staging request to identify the actual thrown exception. Compare a route that never touches Supabase, an HTTPS API call and a direct SQL query where relevant. A generic 500 Internal Server Error response should not be the only diagnostic evidence.
3. Fix the smallest proven fault
Examples include restoring a missing binding, moving a PostgreSQL client into the handler, closing connections in a finally block, correcting a database endpoint, or replacing an inappropriate direct SQL call with a supported Supabase API operation. Do not migrate the entire database just because one runtime integration is wrong.
4. Check for hidden data inconsistency
A timeout after a write does not prove the write failed. If the app processes purchases, bookings or subscriptions, verify the authoritative transaction state before retrying. Repeated payment or order submissions need idempotent handling and reconciliation.
There is another trap: Hyperdrive query caching can return an older eligible read after a write. Its documented defaults include a 60-second cache age and a stale-while-revalidate window. Use cache-disabled access for freshness-critical permissions, billing state and immediate read-after-write checks; caching may be useful for public catalogue reads.
5. Prove the fix survives production behavior
A single successful local request is insufficient. Test repeated requests, concurrent users, cold and warm Worker invocations, login, permission-denied cases, write/read consistency and a controlled deployment rollback. Record before-and-after errors and latency.
For broader Supabase outages or PostgREST 503/PGRST errors, my Supabase production recovery guide covers the database-side diagnosis. This article is specifically about the Cloudflare Workers migration boundary.
What should a developer charge to repair it?
These are my illustrative scoping allowances, not independently surveyed market prices or fixed quotations:
| Engagement | Planning allowance | Deliverable |
|---|---|---|
| Focused diagnosis | $400–$1,200 | Reproducible fault, risk assessment and written repair scope |
| Worker/Supabase integration repair | $1,200–$4,500 | Tested connection or API fix, deployment and handoff |
| Broader backend refactor or recovery | $4,500+ | Multiple affected workflows, migrations, reconciliation and monitoring |
A configuration typo should not be priced like a backend rebuild. Conversely, an app with inconsistent payment state, fragile authentication and undocumented schema changes is not a one-hour connection fix. Ask for a scoped diagnosis before approving a large rewrite.
A useful quotation should say which routes are affected, which connection method will remain, what must change, what is explicitly excluded, how production will be protected and what tests establish completion.
Six acceptance tests before you pay the final invoice
- The original failing production route works under repeated and concurrent requests, not just once in local development.
- A cold Worker and a reused warm isolate both complete database operations without stale-connection errors.
- An unauthorized user cannot read or modify another user’s data; a connection repair must not weaken RLS or server authorization.
- A failed or delayed write has a safe retry and reconciliation path, especially for payments and bookings.
- Freshness-critical reads return the expected post-write state; any Hyperdrive cache is configured deliberately.
- The owner receives GitHub access, Worker and Supabase configuration documentation, deployment instructions, monitoring access and a tested rollback plan.
My production logging guide and AI-built app regression testing guide explain how to keep these guarantees after the first repair.
Fix the integration before replacing the product
If your app worked before moving to Cloudflare Workers, the migration itself is a strong investigative clue—not proof that Cloudflare or Supabase is at fault. Keep the useful product, isolate the failing boundary, and replace only what evidence shows is unreliable.
If you have a live MVP with recurring 500s, broken database routes or uncertain payment state, I can review the failure and scope a responsible repair through my MVP development service. Send the symptoms and current setup—not passwords or API keys—and we can establish whether the next step is diagnosis, a focused fix or a larger rebuild.
