# How to Set File Upload Size Limit in Supabase

- Tool: Supabase
- Difficulty: Beginner
- Time required: 5-10 min
- Compatibility: Supabase (all plans), @supabase/supabase-js v2+
- Last updated: March 2026

## TL;DR

To set a file upload size limit in Supabase, open the Dashboard and go to Storage, select your bucket, click Edit Bucket, and set the maximum file size in bytes. You can also add client-side validation before upload to provide instant feedback. The default limit is 50 MB on free plans. Handle 413 Payload Too Large errors gracefully by checking file size before calling storage.upload().

## Configuring File Upload Size Limits in Supabase Storage

Supabase Storage lets you control the maximum file size for each bucket independently. This tutorial shows you how to configure bucket-level size limits in the Dashboard, add client-side validation to reject oversized files before upload, and handle size-related errors. Setting proper upload limits protects your storage quota, prevents abuse, and provides a better user experience.

## Before you start

- A Supabase project with at least one storage bucket
- Basic knowledge of JavaScript/TypeScript
- The Supabase client library installed in your project

## Step-by-step guide

### 1. Configure the bucket file size limit in the Dashboard

Open your Supabase Dashboard and navigate to Storage in the left sidebar. Click on the bucket you want to configure. Click the three-dot menu or Edit Bucket button. In the configuration panel, you will see a field for maximum file size. Enter the limit in bytes. For example, 5242880 equals 5 MB, and 10485760 equals 10 MB. Click Save. This limit applies to all uploads to this bucket regardless of how the upload is initiated (client SDK, API, or Dashboard).

**Expected result:** The bucket now rejects any file upload that exceeds the configured size limit with a 413 error.

### 2. Create or update a bucket with a size limit via SQL or API

You can also set the file size limit programmatically when creating or updating a bucket using the Supabase client or SQL. The fileSizeLimit property accepts a value in bytes. This is useful when automating bucket creation in migrations or setup scripts.

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

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

// Create a new bucket with a 5 MB limit
const { data, error } = await supabase.storage.createBucket('avatars', {
  public: true,
  fileSizeLimit: 5242880, // 5 MB in bytes
  allowedMimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
})

// Update an existing bucket's size limit
const { data: updated, error: updateError } = await supabase.storage.updateBucket('avatars', {
  fileSizeLimit: 10485760, // 10 MB in bytes
})
```

**Expected result:** The bucket is created or updated with the specified file size limit.

### 3. Add client-side file size validation before upload

Always validate the file size on the client before uploading. This provides instant feedback to the user and avoids wasting bandwidth on uploads that will be rejected by the server. Check the File object's size property and compare it against your limit. Show a clear error message if the file is too large.

```
const MAX_FILE_SIZE = 5 * 1024 * 1024 // 5 MB

function validateFileSize(file: File): { valid: boolean; message: string } {
  if (file.size > MAX_FILE_SIZE) {
    const sizeMB = (file.size / (1024 * 1024)).toFixed(1)
    return {
      valid: false,
      message: `File is ${sizeMB} MB. Maximum allowed size is ${MAX_FILE_SIZE / (1024 * 1024)} MB.`,
    }
  }
  return { valid: true, message: '' }
}

async function uploadFile(file: File, bucket: string, path: string) {
  const validation = validateFileSize(file)
  if (!validation.valid) {
    throw new Error(validation.message)
  }

  const { data, error } = await supabase.storage
    .from(bucket)
    .upload(path, file, {
      cacheControl: '3600',
      upsert: false,
    })

  if (error) throw error
  return data
}
```

**Expected result:** Oversized files are rejected immediately on the client with a clear error message, without making a network request.

### 4. Handle 413 Payload Too Large errors

Even with client-side validation, always handle the server-side 413 error. This catches edge cases where the client check is bypassed or the file size changed between validation and upload. The Supabase storage client returns an error object with a statusCode field. Check for 413 and show a user-friendly message.

```
async function handleUpload(file: File) {
  try {
    const { data, error } = await supabase.storage
      .from('documents')
      .upload(`uploads/${file.name}`, file)

    if (error) {
      if (error.message.includes('Payload too large') || error.message.includes('413')) {
        console.error('File exceeds the bucket size limit.')
        // Show user-friendly message
        return { success: false, message: 'This file is too large. Please upload a smaller file.' }
      }
      throw error
    }

    return { success: true, path: data.path }
  } catch (err) {
    console.error('Upload failed:', err)
    return { success: false, message: 'Upload failed. Please try again.' }
  }
}
```

**Expected result:** 413 errors are caught and displayed as a user-friendly message instead of a generic error.

### 5. Set different limits for different buckets

Supabase lets you configure file size limits independently per bucket. This is useful when you have different upload requirements: small limits for profile avatars, larger limits for document uploads, and even larger limits for video files. Create separate buckets with appropriate limits for each use case. Remember to also set RLS policies on storage.objects for each bucket.

```
-- Create buckets with different size limits using SQL
insert into storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
values
  ('avatars', 'avatars', true, 2097152, '{image/png,image/jpeg,image/webp}'),
  ('documents', 'documents', false, 20971520, '{application/pdf,text/plain}'),
  ('videos', 'videos', false, 104857600, '{video/mp4,video/webm}');

-- RLS policy: users can upload to their own folder
create policy "Users upload to own folder" on storage.objects
  for insert to authenticated
  with check (
    auth.uid()::text = (storage.foldername(name))[1]
  );
```

**Expected result:** Each bucket enforces its own maximum file size and accepted MIME types.

## Complete code example

File: `upload-with-size-validation.ts`

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

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

const BUCKET_LIMITS: Record<string, number> = {
  avatars: 2 * 1024 * 1024,     // 2 MB
  documents: 20 * 1024 * 1024,  // 20 MB
  videos: 100 * 1024 * 1024,    // 100 MB
}

function formatFileSize(bytes: number): string {
  if (bytes < 1024) return `${bytes} B`
  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
}

function validateFile(
  file: File,
  bucket: string
): { valid: boolean; message: string } {
  const maxSize = BUCKET_LIMITS[bucket]
  if (!maxSize) {
    return { valid: false, message: `Unknown bucket: ${bucket}` }
  }
  if (file.size > maxSize) {
    return {
      valid: false,
      message: `File size (${formatFileSize(file.size)}) exceeds the ${formatFileSize(maxSize)} limit for ${bucket}.`,
    }
  }
  return { valid: true, message: '' }
}

export async function uploadFile(
  file: File,
  bucket: string,
  userId: string
): Promise<{ success: boolean; path?: string; error?: string }> {
  // Client-side validation
  const validation = validateFile(file, bucket)
  if (!validation.valid) {
    return { success: false, error: validation.message }
  }

  // Upload to user-scoped folder
  const filePath = `${userId}/${Date.now()}-${file.name}`

  const { data, error } = await supabase.storage
    .from(bucket)
    .upload(filePath, file, {
      cacheControl: '3600',
      upsert: false,
    })

  if (error) {
    if (error.message.includes('Payload too large')) {
      return { success: false, error: 'File is too large for this bucket.' }
    }
    return { success: false, error: error.message }
  }

  return { success: true, path: data.path }
}
```

## Common mistakes

- **Setting the file size limit in megabytes instead of bytes in the Dashboard or API** — undefined Fix: The fileSizeLimit value is always in bytes. Multiply MB by 1048576 to get the correct value. For example, 5 MB = 5 * 1024 * 1024 = 5242880 bytes.
- **Only validating file size on the client and not handling server-side 413 errors** — undefined Fix: Always handle the 413 error from the Supabase storage API as a fallback. Client-side validation can be bypassed by modifying the code or making direct API calls.
- **Using the anon key to create or update bucket settings** — undefined Fix: Bucket management operations (create, update, delete buckets) require the service role key. Use the anon key only for file operations like upload and download.

## Best practices

- Set the file size limit per bucket in the Dashboard to enforce limits server-side regardless of client behavior
- Always add client-side validation before upload to provide instant user feedback and save bandwidth
- Use separate buckets with different limits for different file types (avatars, documents, videos)
- Pair file size limits with allowedMimeTypes to prevent unexpected file type uploads
- Store uploaded files in user-scoped folders (userId/filename) and add corresponding RLS policies on storage.objects
- Display file size limits clearly in your upload UI so users know the constraints before selecting a file
- Log upload errors server-side for monitoring while showing user-friendly messages in the UI

## Frequently asked questions

### What is the default file upload size limit in Supabase?

The default maximum file size is 50 MB on the free plan. Pro and Team plans support up to 5 GB per file. You can set a lower custom limit per bucket.

### Can I set different size limits for different file types within the same bucket?

No, the file size limit is set per bucket, not per file type. To enforce different limits for different file types, create separate buckets with their own size limits and allowedMimeTypes.

### What error does Supabase return when a file exceeds the size limit?

Supabase returns a 413 Payload Too Large error with a message indicating the file exceeds the bucket's configured maximum size.

### Can I increase the file size limit beyond 50 MB on the free plan?

No, the free plan has a hard limit of 50 MB per file. Upgrade to the Pro plan to upload files up to 5 GB.

### Does the file size limit apply to uploads from the Dashboard?

Yes, the bucket-level file size limit applies to all upload methods: the JavaScript client, REST API, and the Supabase Dashboard file manager.

### How do I check the current size limit of a bucket?

Query the storage.buckets table in the SQL Editor: SELECT id, name, file_size_limit FROM storage.buckets; The file_size_limit column shows the limit in bytes.

### Can RapidDev help configure storage limits and policies for my project?

Yes, RapidDev can set up your storage buckets with appropriate size limits, MIME type restrictions, and RLS policies tailored to your application's requirements.

---

Source: https://www.rapidevelopers.com/supabase-tutorial/how-to-set-file-upload-size-limit-in-supabase
© RapidDev — https://www.rapidevelopers.com/supabase-tutorial/how-to-set-file-upload-size-limit-in-supabase