---
title: Reading Large Files in Capacitor Without base64
description: Why a Capacitor app runs out of memory when it reads a large file with readFile, and how to read the file as a Blob without base64 on Android, iOS and the web.
date:
created: 2026-10-30
updated: 2026-10-30
authors:
- robingenz
categories:
- Capacitor
- Guides
- SDKs
links:
- Capacitor File Manager: sdks/capacitor/file-manager.md
faq: true
---
# Reading Large Files in Capacitor Without base64
Reading a large file in a Capacitor app fails in a predictable way: the app asks the Filesystem plugin for the file, the plugin answers with one base64 string, and on a video or a map archive of a few hundred megabytes that string is what runs the WebView out of memory. This guide explains where the memory goes, compares the ways to read a file in Capacitor, and shows how to get the file as a `Blob` with the [Capacitor File Manager plugin](../../sdks/capacitor/file-manager.md) and use it without ever decoding it. Its [`readFileAsBlob(...)`](../../sdks/capacitor/file-manager.md#readfileasblob) method streams the file with no base64 step in between. The plugin is part of [Capawesome Insiders](../../insiders/index.md); the free path with `fetch` and `convertFileSrc` is covered as well.
**Key takeaways:**
- `readFile(...)` of `@capacitor/filesystem` returns a string on Android and iOS, so a 100 MB file crosses the bridge as about 133 MB of base64 and sits in the WebView heap before your code sees a byte.
- Capacitor issue #984, "Support blob/large data", was closed as not planned in January 2024 with the note that plugins should handle it.
- `readFileAsBlob(...)` of the Capacitor File Manager plugin returns a `Blob` through the WebView's local file server on Android and iOS and from the Origin Private File System on the web, with no base64 step and no bridge message.
- A `Blob` costs no heap until you decode it; hand it to `URL.createObjectURL`, `FormData` or `blob.stream()`, and reserve `arrayBuffer()` for files that fit in memory.
- Use `readFile(...)` with `offset` and `length` for a header or a byte range, never in a loop over a whole file.
## Where the memory goes
The Capacitor bridge carries plugin results as JSON messages, so a plugin that returns file contents has to return them as a string. For [`readFile(...)`](https://capacitorjs.com/docs/apis/filesystem#readfile){:target="_blank"} of `@capacitor/filesystem` that string is base64 unless you ask for UTF-8, and the documentation states that on native "the data is returned as a string" while a `Blob` is "only available on Web". A 100 MB file therefore becomes a 133 MB base64 string (base64 encodes three bytes as four characters), held in native memory, serialized into the bridge message, parsed into a JavaScript string, and finally decoded by your code into a 100 MB `Uint8Array`. Several copies of the file exist at once, and none of them is the file you wanted.
Android enforces a heap limit per app, and the crash looks like the one quoted in [Capacitor File Handling: The Complete Guide](./capacitor-file-handling-guide.md): an `OutOfMemoryError` with a growth limit of 268435456 bytes, which is 256 MB. The Filesystem documentation's answer is that working with large files "may require you to add" `android:largeHeap="true"` to the manifest, which raises the ceiling without removing it. On iOS, WebKit runs the page in a separate web content process with its own memory limit, and when the page exceeds it, iOS terminates that process; the symptom is a blank WebView rather than a stack trace.
The problem is as old as Capacitor. Issue [#984](https://github.com/ionic-team/capacitor/issues/984){:target="_blank"}, opened in November 2018 to "investigate passing blobs from native to JS and vice versa", collected reports of crashing WebViews for five years before it was closed as not planned in January 2024 with the comment that "this should be handled by plugins". A forum thread from 2021 about 300 MB KML files reached the same conclusion, and the workaround given there is the one this guide builds on.
## Four ways to read
Capacitor apps have four ways to get a file's contents into JavaScript, and they differ in what crosses the bridge:
| Method | Package | What crosses the bridge | Memory | Platforms |
| --- | --- | --- | --- | --- |
| `readFile(...)` | `@capacitor/filesystem` | Whole file as base64 or UTF-8 string | Whole file plus the encoding overhead | Android, iOS, web |
| `readFileInChunks(...)` | `@capacitor/filesystem` 7.1.0+ | One base64 string per chunk | One chunk at a time | Android, iOS |
| `fetch(Capacitor.convertFileSrc(path))` | `@capacitor/core` | Nothing; served by the WebView's local server | A `Blob`, disk-backed | Android, iOS |
| `readFileAsBlob(...)` | Capacitor File Manager | Nothing on native; Origin Private File System on web | A `Blob`, disk-backed | Android, iOS, web |
`readFileInChunks(...)` arrived in Filesystem 7.1.0 and passes the file to a callback in pieces of `chunkSize` bytes, with an empty chunk marking the end. Each piece is still a base64 string, and if you concatenate the pieces to get the whole file, you are back at a whole-file string with extra steps. It suits a parser that consumes each chunk and discards it, and it has no web implementation.
The `fetch` path and `readFileAsBlob(...)` share a mechanism. Capacitor serves the app's files through a local server inside the WebView, and `Capacitor.convertFileSrc(...)` turns a `file://` path into a URL on that server. Fetching that URL streams the bytes from disk into the WebView's blob storage without a bridge message and without base64. Chromium's [blob storage](https://chromium.googlesource.com/chromium/src/+/HEAD/storage/browser/blob/README.md){:target="_blank"} pages blobs to disk when its in-memory space fills up, which is why a `Blob` of a few hundred megabytes does not count against the heap the way a string does. The Capacitor File Manager plugin does the same two steps on native when you call `readFileAsBlob(...)`, and on the web it reads from the Origin Private File System, where the plugin keeps its files.
## Read as a Blob
To read a large file as a `Blob` in Capacitor, build the file's URI with [`getUri(...)`](../../sdks/capacitor/file-manager.md#geturi) and pass it to `readFileAsBlob(...)`:
```typescript
import { Directory, FileManager } from '@capawesome-team/capacitor-file-manager';
const readVideo = async (): Promise => {
const { uri } = await FileManager.getUri({
path: 'downloads/lesson-12.mp4',
directory: Directory.Data,
});
const { blob } = await FileManager.readFileAsBlob({ uri });
return blob;
};
```
The method rejects with `FILE_NOT_FOUND` when the file does not exist and with `READ_FAILED` for any other failure, so the error handling is a branch on `error.code` rather than a match on a message. Any URI the plugin hands you works as input, including the `uri` of an entry from [`readDirectory(...)`](../../sdks/capacitor/file-manager.md#readdirectory) and the URI returned by a copy or move; the documentation states that the URIs of a persisted directory and its contents are accepted by every method of the plugin, so a file in a folder the user picked reads the same way.
If your files live in the app's sandbox and you do not need the web, you can do the same without the plugin. Call `Capacitor.convertFileSrc(path)` on the `file://` path and fetch the result, as the file handling guide shows with a camera photo. The plugin adds the named error codes, one call that also works on the web, and the URI model it shares with its other methods, so a byte range, a checksum and a `Blob` of the same file use the same `uri`.
## Use the Blob
A `Blob` is a handle to bytes, not the bytes themselves, and the point of this guide is to pass that handle on instead of decoding it. Four patterns cover most apps.
To display the file, create an object URL and give it to an element:
```typescript
const showVideo = (blob: Blob, video: HTMLVideoElement) => {
const url = URL.createObjectURL(blob);
video.src = url;
video.onended = () => URL.revokeObjectURL(url);
};
```
The same URL works as the `src` of an ``, the `href` of a download link and the `data` of an `
