iOS 26 Media elements fail to load/play local files.

[sonlichao]

Bug Report

Problem

What is expected to happen?

Local media files should be accessible via fileEntry.toURL() URLs in HTML media elements (video, audio, img) on iOS 26, maintaining backward compatibility with existing Cordova apps.

What does actually happen?

On iOS 26, fileEntry.toURL() returns file:/// URLs that cannot be loaded in media elements. The browser console shows:

WebContent[3,768] Could not create a sandbox extension for '<private>'
Media elements fail to load/play local files.

Information

Command or Code

// Save file using cordova-plugin-file
window.resolveLocalFileSystemURL(cordova.file.tmpDirectory, (dirEntry) => {
    dirEntry.getFile(fileName, { create: true }, (fileEntry) => {
        fileEntry.createWriter((fileWriter) => {
            fileWriter.onwriteend = () => {
                // Get URL using official API
                const fileURL = fileEntry.toURL();
                console.log(fileURL); 
                // Output: file:///var/mobile/Containers/Data/Application/.../tmp/video.mp4
                
                // This fails on iOS 26 with sandbox error
                document.getElementById('videoElement').src = fileURL;
            };
            fileWriter.write(blob);
        });
    });
});

Environment, Platform, Device

Platform: iOS 26.0
Device: iPhone SE (3rd generation)
WebView: WKWebView (default)
Configuration: Default Cordova setup (no custom scheme/hostname)

Version information

Cordova CLI: 12.0.0
Cordova iOS: [7.1.0]
Cordova Plugin File: 8.1.3

Additional Context
Working Configuration (with critical side effect):
Adding scheme configuration makes file URLs work:

<preference name="scheme" value="app" />
<preference name="hostname" value="localhost" />

However, this causes complete data loss:

Then toURL() returns: app://localhost/app_file/... (works)
However, this causes complete data loss:

• Origin changes from null to app://localhost
• All localStorage, IndexedDB, cookies are permanently lost
• No migration path exists for user data

This creates an impossible choice:

Keep app working without scheme = No file access on iOS 26
Add scheme configuration = Lose all user data

Tested Scenarios

✅ Same code works on iOS18 and earlier
✅ Same code works on all Android versions
❌ Manual URL conversion file:// to app:// fails (CSP error)
❌ File URLs fail in all locations (tmp, documents, cache)

Checklist

• I searched for existing GitHub issues
• I updated all Cordova tooling to most recent version
• I included all the necessary information above

[dpogue]

This sounds like an upstream WebKit issue and not something that Cordova can work around. WebKit's support for file:/// URLs has been getting more and more strict over the past several years to try to reduce security risks. You can try submitting this as an issue with a reproducible test case on https://bugs.webkit.org and Apple Feedback Assistant, but I suspect they won't fix it.

The recommended option (and the default for newly created Cordova apps) is to use a local scheme, unfortunately that does come with data migration issues that you identified.

There are some plugins that might be able to help with migrating data (although these were mostly intended to migrate from UIWebView to WKWebView rather than from file:/// to app://localhost): https://github.com/kassamina/cordova-plugin-ionic-migrate-storage#thanks

[sonlichao]

Update: allowFileAccessFromFileURLs no longer works on iOS 26

I want to add critical information about what has changed in iOS 26.

What worked before (iOS ≤ 25):

We could enable file:// URL access in WKWebView using:

WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
[config.preferences setValue:@YES forKey:@"allowFileAccessFromFileURLs"];

Current situation (iOS 26):
This configuration is completely ignored. The allowFileAccessFromFileURLs preference no longer has any effect on iOS 26.

[dpogue]

Interesting... from what I understand, the [config.preferences setValue:@YES forKey:@"allowFileAccessFromFileURLs"]; code should cause a crash in iOS 18 and newer.

That was never part of the public WebKit API and was never meant to be used because it modified internal state, and WebKit started blocking access. See WebKit/WebKit#26996 & WebKit/WebKit#27476 for context.

[sonlichao]

Alternative Approach: Leverage Existing WKURLSchemeHandler Implementation

While investigating this issue, I noticed that Cordova-iOS already has WKURLSchemeHandler implementation (introduced in v6.0.0 via PR #781). I'm wondering if we can leverage this existing infrastructure to address the iOS 26 media file issue without requiring data migration.

Background

This issue is related to earlier discussions:

• Support serving local content with WKURLSchemeHandler #415 - Support serving local content with WKURLSchemeHandler
• breaking: Use WKURLSchemeHandler for serving app content #781 - Use WKURLSchemeHandler for serving app content
• Allow plugins to hook into the WKURLSchemeHandler #1030 - Allow plugins to hook into the WKURLSchemeHandler

Current Situation

When using the recommended custom scheme configuration:

<preference name="scheme" value="app" />
<preference name="hostname" value="localhost" />

What works:

• Media files load correctly (solves iOS 26 sandbox issue)
• CORS issues are resolved

The problem:

• Origin changes: null → app://localhost
• All localStorage, IndexedDB, and cookies are permanently lost
• No migration path for existing user data

Proposed Investigation

Since Cordova-iOS already uses WKURLSchemeHandler to serve app content from app://localhost, could we extend this handler to also proxy access to temporary directory files (cordova.file.tmpDirectory, cordova.file.cacheDirectory, etc.)?

Conceptual approach:

App content: Served via existing WKURLSchemeHandler

app://localhost/index.html → www/index.html (already works)

Temporary files: Extend handler to support special path prefixes

app://localhost/_tmp/video.mp4 → tmp/video.mp4 (needs implementation)
app://localhost/_cache/audio.mp3 → cache/audio.mp3 (needs implementation)
app://localhost/_documents/file.pdf → Documents/file.pdf (needs implementation)

File URL conversion: Extend or create helper method

// Convert file:// URLs returned by cordova-plugin-file
const fileURL = fileEntry.toURL(); 
// Returns: file:///var/mobile/.../tmp/video.mp4

const appURL = convertFileToAppScheme(fileURL);
// Would return: app://localhost/_tmp/video.mp4

videoElement.src = appURL; // Works on iOS 26

Key Benefits

1. No data migration needed - Storage remains accessible under app://localhost origin
2. Builds on existing infrastructure - PR breaking: Use WKURLSchemeHandler for serving app content #781 already implemented the foundation
3. Similar to proven solutions - Ionic WebView plugin uses this approach successfully
4. Simpler for developers - Just convert file URLs, no complex migration logic
5. Lower risk - Avoids cookie migration reliability issues

Potential Challenges

1. Security: Need to ensure scheme handler doesn't allow access outside allowed directories
2. Path mapping: Need robust conversion between app:// URLs and file system paths
3. Backward compatibility: Existing users still need one-time data migration (but simpler than cookie migration)
4. MIME types: Handler must correctly identify content types for all file types

Questions for Community

1. Is this approach technically feasible given the current CDVWKWebViewEngine implementation?
2. Are there security concerns with allowing scheme handler to access tmp/cache/documents directories?
3. Has anyone already tried extending the scheme handler for this purpose?
4. Would this be worth exploring as an official solution, or are there fundamental blockers?

Testing Plan

I plan to test this approach on:

• Real iOS devices (16, 17, 18, 26) - simulator behavior differs significantly
• Both scenarios: fresh installs and upgrades from file:// scheme
• Memory constraints (WKWebView has strict limits on real devices vs simulators)
• All Cordova file plugin directories (tmp, cache, documents, dataDirectory)

Will report findings back to this issue.

Has anyone explored this direction? I'd appreciate any technical insights, concerns, or references to existing implementations before investing significant effort in this approach.

---

Related Resources:

• WKURLSchemeHandler Apple Documentation
• Ionic WebView Plugin (uses similar approach)
• WebKit Bug #154916 (Apple engineer recommends WKURLSchemeHandler for local content)

[dpogue]

That approach might work, but I think you might need a custom plugin to implement the scheme handling. Currently the WKURLSchemeHandler is only set up if the app is not using file:/// URLs.

[breautek]

First things first, I believe this is likely already solved if you can enable URL schemes and use the file plugin.

Is this approach technically feasible given the current CDVWKWebViewEngine implementation?

Yes, in fact the WKURLSchemeHandler is the recommended path, though I believe iOS still uses file:// protocol by default primarily to avoid introducing a breaking change (I believe the feature was introduced as part of a minor upgrade at the time, iirc).

Loading your web app over a scheme handlers avoids a lot of problems relating to CORS (Cross Origin Resource Sharing) and other browser features that are locked behind a "secure" context.

Are there security concerns with allowing scheme handler to access tmp/cache/documents directories?

Not that I'm aware of. This should already be possible with the file plugin. If you can obtain the FileEntry, you can call .toURL() to get a DOM-usable URL where content is fetched over the scheme handler. It's DOM-usable in the sense that you can use the given URL directly in the DOM (e.g. image tags). The app still lives in a filesystem sandbox.

The scheme handler is only invokable by that specific instance of the webview, so no other app can make use of it, in short of your app introducing a Remote Code Execution vulnerability by allowing untrusted code to execute within the context of your app.

Has anyone already tried extending the scheme handler for this purpose?

Cordova plugins does expose a hook, (See https://github.com/apache/cordova-ios/blob/master/CordovaLib/include/Cordova/CDVPlugin.h#L196) but I'm not sure how useful that is. I honestly thought the File plugin made use of it, but upon reviewing the code it doesn't seem like it. Maybe the core platform might just handle the fetching in generic fashion, or maybe I'm just simply wrong and the file plugin doesn't handle routing to cache or tmp directories... (I'm more familiar with the android implementation than iOS).

All of this does depend on enabling URL schemes however, like dpogue pointed out. And doing so does change the document origin like you have pointed out.

You can't mix and match URL schemes with file:// as that will trigger cross origin sharing.

On the migration issue... I don't know if any of this has changed, but it was possible to migrate storage containers from UIWebView, to WKWebView, or WKWebView from one origin to another. I don't know if each storage mechanism uses the same thing behind the scenes, but local storage was powered by a SQLite database of a given name, found in a particular folder within your app's data directory. Cordova however takes a "hands-off" approach on data migration and if migrating data is important for your app, then it is your responsibility to handle it.

Back when I did it for my own apps, I use https://github.com/totalpave/cordova-plugin-migrate-localstorage/blob/master/src/ios/MigrateLocalStorage.m. The plugin was forked for my own use cases but you can definitely learn about where the files are located and how they should be named. They follow a name pattern of <scheme>_<hostname>_0. On the file:// protocol there is no hostname, the file will be named file__0. If you wanted to use app://localhost, then the file just needs to be renamed to app_localhost_0.

Now I did my migration from UIWebView -> WKWebView around iOS 11 time, so I don't know if anything has changed since iOS 11. I assume they still use SQLite databases. The plugin also only handles local storage, but I think the stuff like IndexedDB and cookies are use SQLite databases probably following the same file name format, just in their own respective directories if I recall correctly.

Apple has been making additional restrictions since the enforcement of WKWebView regarding file:// resources, and the solution is typically moving to the scheme handlers. So I think at some point migration is inevitable if you truly require retaining web storage data. And if you're in that situation, then I would strongly consider a migration path that moves your web storage data to a location that is independent of the webview itself. I was in the same boat when I tackled this issue and I ended up migrating to an SQLite database instead so that my data is decoupled from the webview implementation, or even the document origin, or even Cordova for that matter.