Solutions to common issues with file uploads, downloads, and storage limits.
Users can't upload files — the upload fails immediately
A few things to check:
- The upload feature wasn't generated correctly. If you added file storage to your app but the upload UI doesn't work, it's possible the AI generated the backend storage component without a fully functional frontend upload form. Describe the issue in the chat: "The file upload on the profile page isn't working — please fix it."
- Your app enforces its own file size limit. If you previously asked the AI to add a file size restriction to your app, uploads that exceed that limit will be rejected at the app level. You can change or remove this limit by asking the AI: "Remove the file size limit from the upload form."
- Network or timeout issue. For large files on slow connections, see the section below on uploads that stall.
Uploads start but never complete
Large file uploads are split into 1 MB chunks sent in parallel. If the upload stalls or never finishes:
- Check the user's internet connection — uploading large files on a slow or unstable connection can time out.
- The upload client retries failed chunks automatically (up to three times with increasing delays). If all retries fail, the upload will abort. A poor connection is the most common cause.
- If uploads consistently fail even on good connections, contact support with your project name and a description of the file size and type being uploaded.
Files upload successfully but don't appear in the app
This usually means the frontend isn't re-fetching the file list after an upload completes. Try describing the fix in the chat: "After a user uploads a file, the gallery doesn't update automatically — it only shows the new file after a page refresh."
A file appears broken or won't load
If a file was uploaded but displays as broken or fails to load:
- The upload may have been interrupted partway through, resulting in an incomplete file. Ask the user to re-upload.
- The file type may not be supported for inline display in the browser (for example, some video formats). The file may still be downloadable even if it can't be previewed.
- If the issue only affects one specific file, it may be corrupted. The upload protocol verifies chunk integrity, but if the source file was already damaged, the corrupted data is stored faithfully.
I want users to only be able to upload certain file types
File type restrictions are not built into the storage component by default — the AI generates permissive uploads unless you ask otherwise. Describe what you want in the chat:
- "Only allow users to upload JPG, PNG, or WebP images"
- "Restrict uploads to PDF files only"
- "Block video uploads — images and documents only"
The AI adds the appropriate validation to both the frontend (for immediate feedback) and the backend (for enforcement).
I want to restrict who can upload or view files
File storage doesn't have built-in access control — access is determined by how your app's code is written. To add restrictions, describe them in the chat:
- "Only logged-in users should be able to upload files"
- "Only admins can upload; all users can view"
- "Files should only be visible to the user who uploaded them"
If your app already has the authorization component (role-based access control), the AI will use it to enforce these restrictions.
Uploaded files are accessible to anyone with the URL
This is expected behavior. Files stored in Caffeine's storage gateway are served to anyone who has the full file URL — there is no login check at the file delivery layer. Access control is applied by your app: if your app restricts which users can retrieve a file's URL, those users can't access it.
If you need stricter file privacy — for example, signed or expiring URLs — this is not currently supported. Contact support to discuss your use case.
Deleted files are still showing up
When a file reference is deleted from your canister, Caffeine's infrastructure removes the actual file data from the storage gateway in the background. This cleanup is not instantaneous. If a recently deleted file is still loading from a direct URL, it may simply be that the deletion hasn't propagated yet. Wait a few minutes and try again.
If deleted files persist in your app's UI after deletion, the issue is likely that the frontend isn't refreshing the file list correctly. Describe it in the chat: "After deleting a file, it still shows up in the list until I refresh the page."
Something else isn't working with file uploads
Describe the problem in the chat with as much detail as possible — what you asked for, what the user is experiencing, and what you expected to happen. The AI can update the generated code to fix most issues. For persistent problems, contact support.