Supabase Free plan over quota (egress, cached egress, logs): find the cause and get your app back
Supabase says your organization exceeded the Free Plan quota, or your Lovable, Bolt, or Cursor app started failing after the grace period. How to find what is using egress, cut it, handle the new log meters, and get through to the next billing cycle.
Free · no card
Paste your error. Get a free diagnosis by email.
Tell us what broke and we’ll email you a short diagnosis: the likely cause and what to try first. Usually within a day.
What you are seeing
- Supabase emailed you, or the dashboard shows a banner, that your organization exceeded the Free Plan quota. The Usage page shows Egress or Cached Egress above 100%, sometimes alongside Log Ingestion or Log Query.
- After the grace period ends, the app starts failing: Supabase's Fair Use Policy lists restrictions such as API requests answered with status
402, the database switched to read-only, or projects paused. - You have only a handful of users, but egress keeps climbing, often right after you added images, video, or a feed that loads a whole table.
- Usage is back under the limit, but the dashboard still says your grace period is over.
Why it happens
- Egress is every byte Supabase sends out: database responses through the API, Auth, Storage downloads, Edge Function responses, Realtime messages, and the shared pooler. Per Supabase's docs, the Free Plan includes 5 GB of uncached egress and 5 GB of cached egress per billing cycle, shared by every project in the organization.
- Storage files are served at full size and downloaded again on every view: no
cacheControlon upload, a mobile app with no image cache, or a new signed URL created on every render, so the browser never reuses its copy. - Queries return far more than the screen needs:
select('*')on a list with no pagination, polling on a timer, a React effect that refetches in a loop, or Realtime subscribed to a whole busy table. - Log meters are new. Supabase started showing Log Ingestion (1 GB included on Free) and Log Query in September 2026. Per its changelog, these limits are not enforced yet and existing organizations have a grace period through early 2027, so a log warning alone is informational for now. Typical log volume drivers are
log_statement = 'all', a very lowlog_min_duration_statement,raise noticein a function that runs on every request, and chattyconsole.login Edge Functions. - Usage already served cannot be undone. Supabase's docs say pausing or deleting a project stops new usage but does not remove usage from the current cycle, and after one grace period the next overage is restricted without another.
How to fix it
1. Find which meter and which project
Open your organization's Usage page in the Supabase Dashboard, pick each project from the dropdown, and hover the days where Total Egress jumps: the tooltip breaks it down by service (Database, Storage, Auth, Functions, Realtime). That tells you which of the next steps matters.
2. Find the API paths sending the most traffic
-- Logs Explorer (Logs, then Explorer), source: edge logs
select request.path as path, count(*) as requests
from edge_logs
cross join unnest(metadata) as m
cross join unnest(m.request) as request
group by path
order by requests desc
limit 20;
3. Find the queries returning the most rows
select calls,
rows,
rows / greatest(calls, 1) as rows_per_call,
left(query, 120) as query
from extensions.pg_stat_statements
order by rows desc
limit 20;
-- or open Advisors, then Query performance, in the Dashboard
4. Cut database egress: fewer columns, fewer rows, fewer calls
// before: every column of every row, refetched on a timer
// const { data } = await supabase.from('posts').select('*');
// after: only what the screen shows, 20 at a time
const { data, error } = await supabase
.from('posts')
.select('id, title, cover_path, created_at')
.order('created_at', { ascending: false })
.range(0, 19);
// on insert or update, only chain .select() if you need the row back
await supabase.from('posts').insert(newPost);
5. Cut Storage egress: cache files and keep URLs stable
// cache uploaded files in the browser for a year (value is in seconds)
await supabase.storage.from('media').upload(path, file, {
cacheControl: '31536000',
upsert: false,
});
// public bucket: the URL never changes, so browsers and the CDN reuse it
const { data } = supabase.storage.from('media').getPublicUrl(path);
// private bucket: create one signed URL and reuse it until it expires,
// instead of a new URL on every render
// also: resize and compress images before upload (image transformations
// are a Pro feature) and set a file size limit on the bucket
6. Check the log settings if Log Ingestion is high
select current_setting('log_statement') as log_statement,
current_setting('log_min_duration_statement') as log_min_duration_statement,
current_setting('pgaudit.log', true) as pgaudit_log;
-- 'ddl' is Supabase's default for the postgres role; 'all' logs every query
alter role postgres set log_statement = 'ddl';
-- then remove raise notice / raise log from functions called on every
-- request, and console.log of whole payloads from Edge Functions
7. Get through the rest of the cycle
Supabase's docs give two ways out: restrictions caused by usage lift once the quota refills at the start of the next billing cycle (the Billing page shows the date under Upcoming Invoice), or immediately if you upgrade the organization to Pro, which includes 250 GB of uncached egress. Pausing or deleting the project does not lower the number you already used. If heavy media is the cause, serving it from separate object storage or a CDN keeps it off your Supabase egress entirely.
8. Tell your AI tool the rules
Add to your project rules (.cursorrules, Lovable knowledge, or Bolt prompt): "For lists, never fetch every column with '*'; request only the displayed columns and paginate with range(). No polling loops. Upload files with cacheControl set and reuse their URLs. No console.log of full payloads in Edge Functions."
How to know it is fixed
Over the next day or two, the per-service egress on the Usage page drops for the service you fixed, the Logs Explorer query shows far fewer requests on the top path, and the slow-query list no longer has a query returning thousands of rows per call. After the cycle resets (or you upgrade), API calls stop returning 402 and writes work again. Sources: Supabase: Manage Egress usage, Supabase Billing FAQ (Fair Use Policy and grace period), Supabase Storage optimizations, Supabase: Manage Logs Ingest usage, Supabase changelog: logs usage-based pricing, and Supabase: Postgres log configuration. Related: Supabase paused my free project for inactivity.