Supabase Storage Limits: File Size Caps, Bucket Quotas, and Scaling Solutions

According to official Supabase documentation, the Free plan restricts individual file uploads to 50 MB per object and caps cumulative project storage at 1 GB. For developers evaluating Supabase Storage limits, these tier-based operational constraints govern individual file upload sizes (50 MB on Free, with standard transfers capped at 5 GB on Pro) and total project storage capacity. Crossing these thresholds results in immediate upload rejections, unexpected build failures, or ballooning monthly infrastructure invoices.

Supabase structures its object storage on top of AWS S3 and Postgres, exposing buckets through an HTTP REST interface and an S3-compatible gateway. While the underlying infrastructure scales horizontally, the platform imposes rigid limits based on your subscription tier. Understanding how these quotas interact at the project, bucket, and file levels is necessary before deploying customer uploads or large-scale document pipelines.

On Free tier projects, Supabase Storage limits individual file uploads to 50 MB per object. You cannot increase this threshold in project settings, and standard HTTP multipart forms will throw client errors when attempting to transfer assets exceeding this ceiling. Total storage across all public and private buckets cannot exceed 1 GB on Free tier projects. Furthermore, the Free plan does not allow overage billing. When a Free tier project exceeds Supabase Storage limits of 1 GB or reaches 10 GB of bandwidth, Supabase sends warning notices to the billing email and places the project under a temporary grace period. If usage is not brought back under the quota, upload functionality is suspended.

On Supabase Pro plans, projects include 100 GB of storage capacity. For project storage usage exceeding plan quota on Pro tiers, Supabase charges $0.0213 per GB per month. In Supabase Storage settings on Pro plans, administrators can configure an S3-compatible global file size limit up to 500 GB in the dashboard. In Supabase Storage, standard file uploads remain bounded at 5 GB per request on paid plans, but modern chunked protocols allow larger objects to land in your buckets.

How Supabase Calculates Storage Usage

Supabase does not determine storage billing from a single calendar snapshot. Instead, the platform meters storage continuously in Gigabyte-Hours (GB-Hrs). In Supabase Storage metering, one gigabyte-hour represents storing 1 GB of data for one hour across your project buckets. For example, maintaining an archive of 20 GB for 10 hours in Supabase Storage consumes 200 gigabyte-hours of project storage usage.

At the conclusion of a monthly billing cycle, the system divides accumulated GB-Hours by the total hours in that month (such as 744 hours in a 31-day month) to calculate your effective average storage volume. For example, maintaining 100 GB of objects in Supabase Storage for half of a 30-day month results in an average billed project storage usage of 50 GB for that cycle. Because usage is measured as a rolling average, deleting large files late in your billing period reduces the monthly average only gradually. It does not instantly erase accumulated GB-Hour charges for that cycle.

• Google Drive File Size Limits: Workarounds for AI Agent WorkspacesGoogle Drive limits individual file uploads to 5TB and daily uploads to 750GB, which can easily freeze multi-agent...
• Firebase Storage File Size Limit: Client SDKs, Cloud Functions, and Bucket QuotasThe Firebase Storage file size limit reaches 5 TB per object at the Google Cloud Storage bucket layer, but real-world...
• Google Cloud Storage File Size Limits: Object, Upload, and Composite CapsGoogle Cloud Storage enforces an individual object limit of 5 TiB per file. While single-stream HTTP PUT uploads face...
• Best Document Storage for AI Processing: Top Solutions for 2026AI agents need somewhere to store and retrieve documents. Not every cloud storage platform is up to the task. This...
• How to Give AI Agents Secure Cloud File StorageAutonomous agents need more than vector memory. They need actual file storage to read documents, generate reports, and...
• How to Use Supabase Storage for AI AgentsSupabase provides an open-source backend that combines a Postgres database, file storage, and real-time updates into a...

More on this subject: Agent Memory and Storage (304 guides)

Supabase Storage supports three distinct upload mechanisms, each governed by different technical caps and performance tradeoffs. Choosing the wrong upload method often leads to broken network connections or memory crashes long before reaching the plan's theoretical ceiling.

Standard REST API Uploads

The default method exposed by the Supabase JavaScript and Python libraries is the standard upload endpoint:

const { data, error } = await supabase.storage
  .from('documents')
  .upload('reports/annual-analysis.pdf', fileBody, {
    cacheControl: '3600',
    upsert: false
  });

Standard uploads send the entire file payload in a single HTTP POST request. While Supabase permits standard S3-compatible uploads up to 5 GB on paid plans, sending large binary blobs in a single request over mobile or unstable network connections frequently fails. When an HTTP connection drops late in a large standard upload, the client must retransmit the entire payload from byte zero. Official Supabase storage documentation advises that for individual file uploads larger than 6 MB, developers should transition to resumable protocols.

Resumable Uploads via the TUS Protocol

To handle large files reliably, Supabase Storage integrates the open-source TUS (Resumable Upload Protocol) standard. TUS splits files into discrete chunks, transfers each piece sequentially or in parallel, and tracks byte offsets on the server. If a network interruption occurs during a video upload, the client pauses and resumes from the exact byte where transmission stopped.

On Supabase Pro and Team plans, resumable storage file uploads support S3-compatible payloads up to 50 GB. Implementing TUS requires configuring a client library pointed at the Supabase project storage endpoint (https://<project-ref>.supabase.co/storage/v1/upload/resumable). The client must supply an authorization header containing the user's JWT or the service role key, as detailed in the official resumable uploads specification.

S3-Compatible Gateway

Supabase Storage provides an AWS S3-compatible API. This interface allows developers to connect existing tools like the AWS CLI, rclone, or the AWS S3 SDK directly to Supabase buckets. Supabase Storage supports multipart file uploads on its S3 endpoint with individual part sizes ranging from 5 MB to 5 GB, allowing parallel chunk processing for files up to 50 GB.

Configuring Global and Bucket-Level Limits

Upload restrictions operate in a hierarchy where global settings establish the absolute ceiling, and individual buckets can apply tighter boundaries.

-- View current bucket limits and MIME type rules
select id, name, public, file_size_limit, allowed_mime_types
from storage.buckets;

-- Configure a 25 MB limit and restrict file formats on a bucket
update storage.buckets
set
  file_size_limit = 26214400, -- 25 MB in bytes
  allowed_mime_types = array['application/pdf', 'text/markdown', 'image/png']
where id = 'agent-artifacts';

If the project global limit is configured to 50 MB, setting a bucket threshold to 100 MB has no effect because Supabase Storage limits take precedence and will reject the upload.

Object Key and File Naming Rules

Supabase Storage enforces specific naming constraints across all object keys. Keys may contain:

• Alphanumeric characters (A-Z, a-z, 0-9)
• Punctuation characters: _, -, ., ', and ,
• Special symbols: !, *, &, $, @, =, ;, :, +, ?, and ()
• Whitespace characters, though spaces should be URL-encoded in API requests

Object paths are case-sensitive. Storing Invoice.pdf and invoice.pdf within the same folder creates two distinct objects in the bucket schema.

Storage capacity fees represent only one component of your monthly infrastructure expenditure. In data-heavy architectures, storage egress, the volume of data transferred from Supabase servers to client applications, external APIs, or downstream services, often exceeds the cost of resting disk capacity.

For Free tier projects, Supabase Storage bandwidth includes 10 GB monthly, divided into 5 GB cached edge bandwidth and 5 GB uncached origin bandwidth. On Pro plans, Supabase Storage includes 250 GB of monthly project egress. Project bandwidth usage exceeding the 250 GB plan quota incurs egress charges of 9 cents per GB. For applications serving high-resolution media, raw dataset archives, or repeated document downloads, egress charges accumulate rapidly.

Auditing Egress with Edge Logs

Supabase serves storage assets through Cloudflare edge locations. Developers can query edge access logs directly within the Supabase SQL Editor to pinpoint which files generate the greatest egress drain:

select
  log_attributes['request.method'] as http_verb,
  log_attributes['request.path'] as filepath,
  (log_attributes['response.headers.cf_cache_status'] = 'HIT') as cached,
  count() as num_requests
from logs
where source = 'edge_logs'
  and (
    log_attributes['request.path'] like '%storage/v1/object/%'
    or log_attributes['request.path'] like '%storage/v1/render/%'
  )
  and log_attributes['request.method'] = 'GET'
group by http_verb, filepath, cached
order by num_requests desc
limit 50;

When an asset is requested with cache headers, Cloudflare edge servers return a cache HIT, serving the file without drawing down origin compute. However, when files are accessed through dynamically generated signed URLs (/storage/v1/object/sign/), query parameter differences frequently bypass edge caching, forcing every single download to pull directly from the origin bucket and consume billable egress.

The AI Vector Search and Document Ingestion Trap

A common architectural trap occurs when building Retrieval-Augmented Generation (RAG) and autonomous AI agent pipelines on top of Supabase.

In a standard setup, developers place source documents into a Supabase Storage bucket. A background worker or Edge Function reads each file, extracts text, generates vector embeddings, and writes the resulting vectors to Postgres using the pgvector extension.

When an AI agent needs to answer a prompt, it queries pgvector to identify the most relevant document chunks. So far, the process is efficient. The bottleneck emerges during synthesis: autonomous agents often require the complete original document to parse multi-page data tables, inspect surrounding legal context, or re-verify extracted facts.

When autonomous agents repeatedly fetch complete source documents across iterative research loops, data transfer scales with every read cycle. If multiple agents inspect long-form documents to verify citations or extract tables, repeatedly streaming source binaries rapidly exhausts included monthly bandwidth, incurring bandwidth overage penalties on files read purely for text extraction.

Decoupling Object Storage from Agent Workspaces

Teams building agentic systems can eliminate redundant egress cycles by separating raw object storage from the active workspace layer. For passive asset hosting, standard buckets in Supabase, AWS S3, or Google Cloud Storage serve basic downloads adequately.

However, when agents must actively read, search, and co-author knowledge bases, an intelligent workspace layer provides a more practical model. In Fast.io workspaces, storage is structured specifically for human and agent collaboration. Instead of forcing an agent to download a multi-megabyte document over an HTTP endpoint just to read two paragraphs, Fast.io workspaces feature Intelligence Mode, which automatically indexes uploaded documents for semantic search, keyword retrieval, and citation-backed extraction.

Agents connect to workspaces using the remote Model Context Protocol (MCP) server: Claude and general MCP clients use https://mcp.fast.io/mcp/tools, and coding agents use https://mcp.fast.io/mcp/code. Through standard MCP tool calls, an agent searches the indexed workspace corpus and retrieves precise, cited text snippets without transmitting large source files over public network pipes.

Monthly plans start with a 14-day free trial, which requires a credit card. Subscription tiers are Starter at $9.99/mo, Business at $49.99/mo, and Enterprise at $199.99/mo on Fast.io pricing.

Additional storage beyond the plan allowance is billed at 1.5 cents per GB per month, and bandwidth beyond plan limits is billed at 4 cents per GB. Credits meter AI operations, with overage billed at $10 per 100,000 credits. Dedicated capabilities for agent environments are documented at Fast.io storage for agents.

Overcome Supabase Storage Limits with Agent Workspaces

When your AI agent pipelines exceed Supabase storage limits, Fast.io provides persistent workspaces with automatic semantic indexing, version history, and remote MCP access. Starts with a 14-day free trial.

Start 14-Day Trial

When an application breaches Supabase Storage limits, the platform returns specific HTTP status codes and error payloads. Identifying the root cause quickly prevents extended downtime and user-facing disruptions.

Common Storage Error Responses

• HTTP 413 Payload Too Large: This error occurs when an uploaded file exceeds Supabase Storage limits (50 MB on Free tier projects) or a specific bucket-level size ceiling. The Supabase client library returns an error object containing statusCode: '413' and a message stating that the payload size exceeds configured limits. To fix this, verify whether the bucket setting or the global project setting is the active constraint.
• HTTP 400 Invalid Mime Type: If a bucket has allowed_mime_types defined, uploading a file with an unlisted MIME type results in an immediate HTTP 400 rejection. Ensure your client correctly sets the contentType property during the upload call.
• HTTP 403 Access Denied or Row Level Security Violations: Supabase Storage permissions rely on Postgres Row Level Security policies applied to the storage.objects table. If an authenticated user or agent cannot insert or select an object, the request fails with HTTP 403. Check that your RLS policy accounts for the bucket ID and user UID.
• Spend Cap Hard Stops: With the Spend Cap active on Pro plans, Supabase Storage blocks project storage expansion beyond 100 GB or egress beyond 250 GB rather than billing overages. If your project suddenly rejects all new file uploads while existing files remain readable, check your organization billing settings in the dashboard to determine if the Spend Cap was reached. Disabling the Spend Cap allows project storage usage exceeding plan quota to bill at the standard rate.

-- Allow authenticated users to upload files to a specific bucket
create policy "Allow authenticated uploads"
on storage.objects for insert
to authenticated
with check (bucket_id = 'agent-artifacts');

Auditing Storage Consumption via SQL

Because Supabase stores bucket metadata directly within PostgreSQL, developers can audit object sizes and bucket allocations using standard SQL queries in the dashboard:

-- Identify the 10 largest files in your project
select
  name,
  bucket_id,
  case
    when (metadata->>'size')::bigint >= 1073741824
      then round(((metadata->>'size')::bigint / 1073741824.0), 2) || ' GB'
    when (metadata->>'size')::bigint >= 1048576
      then round(((metadata->>'size')::bigint / 1048576.0), 2) || ' MB'
    else (metadata->>'size')::bigint || ' bytes'
  end as formatted_size,
  created_at
from storage.objects
order by (metadata->>'size')::bigint desc
limit 10;

-- Calculate total storage used per bucket
select
  bucket_id,
  count(*) as total_files,
  round(sum((metadata->>'size')::bigint) / 1048576.0, 2) as total_size_mb,
  round(sum((metadata->>'size')::bigint) / 1073741824.0, 2) as total_size_gb
from storage.objects
group by bucket_id
order by sum((metadata->>'size')::bigint) desc;

Running these queries periodically uncovers orphaned test files, oversized media assets, and abandoned agent logs that unnecessarily inflate your monthly GB-Hour balance.

Deploying autonomous AI agents, whether using Claude Code, Cursor, Codex, OpenClaw, or custom multi-agent frameworks, introduces unique storage requirements. Unlike human users who upload a handful of documents manually, autonomous agents generate thousands of intermediate scratchpads, parsed chunks, summary briefs, and structured tables.

Managing this volume inside standard object storage requires deliberate architecture.

Structured Extraction Without Heavy File Transfers

When agents ingest large document batches (such as scanned invoices, loan files, or vendor agreements), traditional architectures require downloading each binary file, passing it to an external optical character recognition (OCR) engine, parsing the output with an LLM, and writing the structured columns to a database table.

This multi-step pipeline generates substantial egress traffic and introduces multiple failure points. A more durable alternative is using Fast.io Metadata Views. Metadata Views turn file collections into live, queryable databases. Users define target fields in plain English, and the platform extracts typed data (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time) across PDFs, spreadsheets, presentations, and images without manual OCR rules. Agents can trigger extraction and query structured data via MCP without streaming heavy source binaries across networks.

Concurrency and State Collisions

Supabase Storage does not provide native file locking or version control on stored objects. If two autonomous agents process the same dataset and upload results to analysis/summary.json with the upsert: true flag, the last write wins. The earlier agent's output is permanently overwritten without an audit trail or recovery path.

In collaborative environments, agents require version preservation and conflict detection. Fast.io provides per-file version history on every write, preserving earlier iterations if an agent makes an unintended edit. Furthermore, Fast.io workspaces support advisory file locks through MCP tools (lock-status on storage, and lock-acquire and lock-release on storage_manage). An agent acquires a temporary lease on a document while analyzing its contents, signaling to peer agents that processing is underway without granting exclusive write rights.

Workspace Ownership Transfer

When software agencies or internal operations teams deploy AI agents to build client solutions, the agent often creates the initial workspace, populates folder structures, and organizes project deliverables. Once the system is established, the agent transfers organization or workspace ownership directly to human stakeholders while retaining administrative access. This allows humans to manage subscriptions and permissions while agents continue automated maintenance via scoped API keys or MCP endpoints.