Error Handling

File uploads can fail for the same reasons as any submission: invalid form ID, storage misconfiguration, or network issues. The Formbase submit endpoint responds with standard HTTP status codes so you can handle errors in your UI. Here is a simple client-side pattern you can reuse.

const response = await fetch('https://formbase.dev/s/YOUR_FORM_ID', {
  method: 'POST',
  body: new FormData(formElement),
  redirect: 'manual',
});

if (response.status === 303 || response.ok) {
  // Success
} else if (response.status === 404) {
  // Form not found
} else {
  // General failure (500 or other)
}

Common error causes

Storage not configured

Formbase throws an error if storage credentials are missing when a file is uploaded. Ensure all STORAGE_* environment variables are set.

Incorrect form ID

A 404 response means the form ID does not exist or is not available in this Formbase instance.

Network failures

Handle timeouts or offline conditions by showing a retry button and preserving form state when possible.

Browser submissions return a 303 redirect on success. Treat 303 as a successful upload.

Allowed File Types Security Considerations

⌘I

Getting Started

Integrations

File Uploads

Form Settings

Redirects

Submissions

Security

Self-Hosting

CMS Platforms

FAQ

Common error causes

​Common error causes

Common error causes