General: Forums subtopic: App & System Services > Core OS Forums tags: Files and Storage, Foundation, FSKit, File Provider, Finder Sync, Disk Arbitration, APFS Foundation > Files and Data Persistence documentation Low-level file system APIs are documented in UNIX manual pages File System Programming Guide archived documentation About Apple File System documentation Apple File System Guide archived documentation File system changes introduced in iOS 17 forums post On File System Permissions forums post Extended Attributes and Zip Archives forums post Unpacking Apple Archives forums post Creating new file systems: FSKit framework documentation File Provider framework documentation Finder Sync framework documentation App Extension Programming Guide > App Extension Types > Finder Sync archived documentation Managing storage: Disk Arbitration framework documentation Disk Arbitration Programming Guide archived documentation Mass Storage Device Driver Programming Guide archived documentation Device File Access Guide for Storage Devices archived documentation BlockStorageDeviceDriverKit framework documentation Volume format references: Apple File System Reference TN1150 HFS Plus Volume Format Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com"

We are creating a Replicated FileProvider based application, where we need to change folder icons for root level folders. I tried below two approaches. This using NSFileProviderDecorations + Custom UTType, this changed the UI as shown: This using Custom UTType, this had no UI change: How can we change the default folder icon, to our custom icon?

I’ve filed this as FB20943098 (macOS 26.1 – FileProvider v3 synchronous enumeration bug), but posting here in case others can reproduce and add duplicates. Systems: macOS 26.1 (26B82) M4 Mac mini Pro and M4 MacBook Air Symptoms: In any app (TextEdit, Pages, Browsers, etc.), the Open/Save dialog lags for ~1s per folder navigation click. CPU spikes from fileproviderd, cloudd, bird, and siriactionsd. Key discovery: If my iCloud Drive root is empty (only “Documents” and “Downloads”), performance is perfect. As soon as any folder or file exists at the root of iCloud Drive, the lag returns immediately. Moving those items into “Documents” or “Downloads” makes everything smooth again. Analysis: Based on process traces and container paths, this appears to originate in the FileProvider.framework subsystem (via fileproviderd), which mediates iCloud Drive. Early evidence suggests that folder enumeration of the iCloud Drive container root may be blocking UI threads in macOS 26.1. I believe this may be related to the recent internal migration of the file-provider backend (often referred to as “v3”), but I do not have direct confirmation from Apple of that exact change. MacOS 26.1’s new FileProvider v3 backend seems to be blocking the Open/Save panel while enumerating the iCloud Drive root container (~/Library/Application Support/FileProvider/723EBBFF-…). Folder enumeration seems to wait synchronously for metadata from fileproviderd, and if the local SQLite DB is busy (WAL writes or sync state checks), UI freezes briefly. Workarounds: Disabling iCloud Drive entirely fixes the issue. Simply disabling Desktop/Documents sync does not help. Keeping the iCloud Drive root empty avoids the lag without turning iCloud off. I am able to store whatever I please in the Desktop or Documents folder which is currently syncing. Would appreciate if others on 26.1 could confirm. Engineers: I’ve attached fs_usage, log stream, and process samples to my Feedback ticket via the FB20943098. Expected behavior: Folder enumeration in NSOpenPanel should remain asynchronous regardless of FileProvider background activity. Open/save modal should be responsive and smooth.

I'm working on an iOS document-based app. It uses ReferenceFileDocument and custom creation of documents via DocumentGroupLaunchScene + NewDocumentButton. It works fine when I use the plain NewDocumentButton("Whatever") (without any more arguments), but when I want to perform additional setup via preapreDocumentURL or even just add a contentType it gives such output in the console when I hit it: Content serialization failed, document won't be saved. UTType.replayable is correctly wired up in the plist. It looks like a bug in the SDK, but maybe there is a chance that I'm doing something wrong? Here's a code: import SwiftUI import UniformTypeIdentifiers import Combine @main struct MyApp: App { var body: some Scene { DocumentGroup { Document() } editor: { documentConfiguration in EmptyView() } DocumentGroupLaunchScene("Yoyo") { NewDocumentButton(contentType: .replayable) { return URL(string: "whatever, it doesnt even go there...")! } } } } final class Document: ReferenceFileDocument { static var readableContentTypes: [UTType] { [.replayable] } @Published var x = 0 init() {} init(configuration: ReadConfiguration) throws {} func snapshot(contentType: UTType) throws -> Data { Data() } func fileWrapper(snapshot: Data, configuration: WriteConfiguration) throws -> FileWrapper { .init(regularFileWithContents: snapshot) } } extension UTType { static var replayable: UTType { UTType(exportedAs: "com.whatever.yo") } }

In the context of a FPUIActionExtensionViewController module the prepare method is defined like this: override func prepare(forAction actionIdentifier: String, itemIdentifiers: [NSFileProviderItemIdentifier]) { So you would expect the itemIdentifiers list to be the item identifier but instead it is a list of the internal fileprovider IDs like: __fp/fs/docID(6595461) So this is a bit problematic because the only way to recover the ID is by using getUserVisibleURL to get the path which is not great. Is there a better way ? Am I missing something ? Thanks,

I face this issue only on macOS 26 and only on the Intel architecture. I'm unable to download files from a file provider's folder when I make them read-only. STEPS TO REPRODUCE Download the sample from https://developer.apple.com/documentation/fileprovider/synchronizing-files-using-file-provider-extensions?language=objc Follow the steps on the page to configure the project. Build the project. Run it. Add a domain. Open the domain's folder in the Finder. Move a file to the domain's folder. Right-click on the file in the domain's folder and select "Remove Download". Close the Finder's window with the domain's folder and kill all the "Provider" processes to get rid of running instances of the extension. Change Item's capabilities in Item.swift to make the items read-only: var result: NSFileProviderItemCapabilities = [ .allowsContentEnumerating, .allowsReading ] Rebuild the project and run it. Open the domain's folder and try to drag and drop the file from the extension's folder to, let's say, the Desktop folder. EXPECTED RESULT The file is copied ACTUAL RESULT A dialog pops up with text "The file “filename” cannot be downloaded. Do you want to skip it?" Stop/Skip

Hi, Is it possible to create an App in USB portable flash drive, which can automatically call iPhone file app, to allow iPhone file app access the content of flash drive, when USB portable flash plug into iPhone?

I am writing an NSFileProviderReplicatedExtension for my app. Every once in a while it will get to a point where NSFileProviderManager.getDomainsWithCompletionHandler { domains, error in DispatchQueue.main.async { if let error = error { completion(.failure(.domainQueryFailed(error))) } else { completion(.success(domains)) } } } this always fails, once this happens then regardless of what I do - clean build, restart machine, uninstall plugin nothing works. The only way to get back to a wokring state is a full reinstall of the OS. It seems like when this happens Finder gets to a weird irrecoverable state that only a restart can fix. When it fails the error is always : The application cannot be used right now. the only way out is reisntall the OS. When this happened last time, I was advised to the use the debugging profile: https://developer.apple.com/forums/thread/797053 I now have that and have the log which is 300MB file, where do I upload it to? My machine is in that state, is there anything else I can run or diagnose to address this?

I have an iOS and macOS app that includes a file provider extension. on macOS is is perfect no issues anywhere. on iOS it works for small datasets or if I do read only operations. as soon as I try to do anything with larger files I quickly hit the 20MB limit. I have solved file transfers by using chunking but when it comes to listing a folder with a couple thousand files it instantly crashes the FPE with an OOM error. works ok up to 100 files but anything beyond that crashes. I know enumerate items supports batches however the initial load form say a webdav server that has no concept of pagination will always fail to load in pieces no matter what I do. This likely explains why WebDAV was never implemented on iOS. in any case can you possibly consider upgrading the memory limit for FPE's or provide some mechanism to call our full iOS app for more processing power in the background to handle requests on demand? I do not understand where 20MB is a reasonable number. even 100MB seems more reasonable with everything have much more memory these days this seems incredibly limiting. even an option to request increased memory with a capability would be fine but that only works for the app itself not the FPE target. please advise if there is anything that can be done.

I am writing an NSFileProviderExtension for my app. Every once in a while it will get to a point where NSFileProviderManager.getDomainsWithCompletionHandler { domains, error in DispatchQueue.main.async { if let error = error { completion(.failure(.domainQueryFailed(error))) } else { completion(.success(domains)) } } } this always fails, once this happens then regardless of what I do - clean build, restart machine, uninstall plugin nothing works. The only way to get back to a wokring state is a full reinstall of the OS. It seems like when this happens Finder gets to a weird irrecoverable state that only a restart can fix. Is there anything I can do to address this? I have a laptop which is in this state. Finder has this image attached

We are creating a Replicated FileProvider based application, where we want to handle different types of errors. As per doc: https://developer.apple.com/documentation/fileprovider/synchronizing-files-using-file-provider-extensions?language=objc#Handle-errors-elegantly NSFileProviderErrorNotAuthenticated is a resolvable error, and once we report it, the system throttles the sync operation until something (most likely the app or extension) calls signalErrorResolved(:completionHandler:) to signal that the user or the server resolves the error. But this is not happening in our app, see below the sample code snippet (showing just error related code to keep it concise): NSProgress* MacFileProvider::modifyItem(....) { NSProgress *nsProgress = [[NSProgress alloc] init]; nsProgress.totalUnitCount = NSURLSessionTransferSizeUnknown; NSError *error = [NSError errorWithDomain:NSFileProviderErrorDomain code:NSFileProviderErrorNotAuthenticated userInfo:nil]; completionHandler(nil, 0, false, error); return nsProgress; } Observed behaviour: On making local edits to a file, though this function returns resolvable error, this function is being called multiple times with retry back-off interval. Also, this function is called when we edit other files as well. Expected behaviour: As we are returning resolvable error, system should have throttled the operation until we resolve the error. So, all sync operation should have stopped for any item. Can someone please help understand this behaviour difference, and how to achieve the expected behaviour.

Hello, we have a file provider based macOS app. Around June we started receiving reports that our users have problems when opening files. Sometimes they get "Invalid argument" alerts after double-clicking on a dataless file. We receive similar errors when trying to materialize the files programmatically from our app (not FP extension)(*): "The operation could not be completed. Invalid argument" code: 22 domain: "NSPOSIXErrorDomain" underlyingError: "cannotMaterialize" code: 33 domain: "libfssync.VFSFileError" We also see those errors with matching timestamps in the output from fileproviderctl dump: > (...) update-item: 🔶 last:(...) (-1min27s) (...) error:'NSError: POSIX 22 "The operation couldn’t be completed. Invalid argument" Underlying={NSError: libfssync.VFSFileError 33 "cannotMaterialize" }}' domain:none category:<nil> (...) At the same time our file provider extension receives fetchPartialContents call or no call at all. If it receives the call it finishes with success and returns correct range: requestedRange: "{0, 15295}" returnedRange: "{0, 524288}" alignment: "16384" Sadly we don't know how to reproduce those issues. We will be grateful for any hints that could be useful in debugging. Some more context: if materializing a file fails with this error, subsequent materialization attempts fail similarly in local testing when downloading a file with the code below, or double-click, we only get regular fetchContents call file returned by fetchPartialContents should have correct size the app is built with XCode 16.1, customers reporting this issue have OS/FP versions: 24F74/2882.120.74 and 24G90/2882.140.30 (*) More or less the code that we use to materialize files func materializeURL(_ url: URL) throws { if try url.isDataless() { var error: NSError? = nil let coordinator = NSFileCoordinator(filePresenter: nil) coordinator.coordinate(readingItemAt: url, error: &error) { _ in } if let error { throw error } } } private extension URL { func isDataless() throws -> Bool { let downloadStatus = try self .resourceValues(forKeys: [.ubiquitousItemDownloadingStatusKey]) .ubiquitousItemDownloadingStatus return downloadStatus == .notDownloaded || downloadStatus == .none } }

I am building a Vision OS app that includes a File Provider and File Provider UI extension. Both work great in simulator. When uploading to TestFlight, this message is shown: Unsupported Platform. The extension bundle [...]/PlugIns/File ProviderUI.appex is not supported for this platform. If I exclude the File Provider UI extension from the build, it is accepted. If I even include a hello-world File Provider UI extension, the error shown above is returned by ASC. There is contradicting documentation on this subject: https://developer.apple.com/documentation/technologyoverviews/app-extensions states that File Provider UI extension is not supported on Vision OS, so that explains ASC behavior https://developer.apple.com/documentation/FileProviderUI (and all other framework docs) states that File Provider UI extension is supported on Vision OS, so that explains why it works on simulator. Now, which of these two is correct? My best guess at this point is that ASC's logic follows the first document linked above, while the OS and framework actually follow the second. The same discrepancy seems to hold for macOS, but I'm currently focusing on Vision OS. Ideas? Anybody using a File Provider UI extension on Vision OS?

I'm using UIDocumentPickerViewController to open a url. Works fine in debug mode but version on the App Store is failing. Code to create the document picker is like: NSArray *theTypes = [UTType typesWithTag:@"docxtensionhere" tagClass:UTTagClassFilenameExtension conformingToType:nil]; UIDocumentPickerViewController *documentPicker = [[UIDocumentPickerViewController alloc]initForOpeningContentTypes:theTypes]; documentPicker.delegate = self;   [self presentViewController:documentPicker animated:YES completion:nil]; So in debug mode this is all gravy. -documentPicker:didPickDocumentsAtURLs: passes back a URL and I can read the file. In release mode I get a URL but my app is denied access to read the file. After inspecting some logging it appears the sandbox is not granting my app permission. error Domain=NSCocoaErrorDomain Code=257 "The file “Filename.fileextensionhere” couldn’t be opened because you don’t have permission to view it." UserInfo={NSFilePath=/private/var/mobile/Library/Mobile Documents/comappleCloudDocs/Filename.fileextensionhere, NSUnderlyingError=0x2834c9da0 {Error Domain=NSPOSIXErrorDomain Code=1 "Operation not permitted"}} -- If I'm doing something wrong with UIDocumentPickerViewController it is a real shame that permission is not being denied in Debug mode, as devs are more likely to catch in prior to release. Anyone know where I'm going wrong and if not have a workaround? Thanks in advance.

This concerns file provider framework on macOS. Some users of our application (Egnyte.app) report that they have problems downloading dataless files. When a file reaches invalid state, trying to open or download it through Finder results in "Invalid argument" alert (see example-recording.mp4). At the same time our FileProvider extension receives no fetchContents or fetchPartialContents calls. A step-by-step set of instructions to reproduce the problem (if possible) So far we don't have clear reproduction steps. The issue is easily reproducible, for multiple files, for some of our customers. See attached sysdiagnose and recording. What results you expected Our extension receives a request to download the file. File downloads and opens successfully. What results you actually saw No download request made to our File Provider extension. File doesn't open, Finder alert instead. PLEASE NOTE: Before recording and collecting sysdiagnose we installed FileProvider.mobileconfig, slightly modified official profile that we attach. Example reproduction happens 8:33 into full-recording.mp4, around 17:01:18 / 17:01:19 machine’s time. Shared sysdiagnose and recordings come from one of our customers, they permitted us to share the data. In the recording they try to open files with multiple 3rd party applications (Vectorworx, Office PowerPoint) and those opens fail with alerts from those applications. We have similar reports from customers using Adobe apps. More info in FB19462434

Hi, The app that I'm developing requires data transfer between iOS device and external device through usb-c cable connection. So I'm trying to copy and paste the file between iOS and external storage device automactically. I've tried using UIDocuementPickerController with bookmark, which gives the url path of connected external storage after user selection for the first selection, but it could not be used directly without user interaction afterwards. Is it possible to use the storage url path automatically after user selection for the first time? How do I achieve that? Thanks in advance

This concerns file provider framework on macOS. Some users of our application (Egnyte.app) report that they have problems downloading dataless files. When a file reaches invalid state, trying to open or download it through Finder results in "Invalid argument" alert (see example-recording.mp4). At the same time our FileProvider extension receives no fetchContents or fetchPartialContents calls. A step-by-step set of instructions to reproduce the problem (if possible) So far we don't have clear reproduction steps. The issue is easily reproducible, for multiple files, for some of our customers. See attached sysdiagnose and recording. What results you expected Our extension receives a request to download the file. File downloads and opens successfully. What results you actually saw No download request made to our File Provider extension. File doesn't open, Finder alert instead. PLEASE NOTE: Before recording and collecting sysdiagnose we installed FileProvider.mobileconfig, slightly modified official profile that we attach. Example reproduction happens 8:33 into full-recording.mp4, around 17:01:18 / 17:01:19 machine’s time. Shared sysdiagnose and recordings come from one of our customers, they permitted us to share the data. In the recording they try to open files with multiple 3rd party applications (Vectorworx, Office PowerPoint) and those opens fail with alerts from those applications. We have similar reports from customers using Adobe apps.

(Using macOS 26 Beta 9 and Xcode 26 Beta 7) I am trying to support basic onDrop from a source app to my app. I am trying to get the closest "source" representation of a drag-and-drop, e.g. a JPEG file being dropped into my app shouldn't be converted, but stored as a JPEG in Data. Otherwise, everything gets converted into TIFFs and modern iPhone photos get huge. I also try to be a good app, and provide asynchronous support. Alas, I've been running around for days now, where I can now support Drag-and-Drop from the Finder, from uncached iCloud files with Progress bar, but so far, drag and dropping from Safari eludes me. My code is as follows for the onDrop support: Image(nsImage: data.image).onDrop(of: Self.supportedDropItemUTIs, delegate: self) The UTIs are as follows: public static let supportedDropItemUTIs: [UTType] = [ .image, .heif, .rawImage, .png, .tiff, .svg, .heic, .jpegxl, .bmp, .gif, .jpeg, .webP, ] Finally, the code is as follows: public func performDrop(info: DropInfo) -> Bool { let itemProviders = info.itemProviders(for: Self.supportedDropItemUTIs) guard let itemProvider = itemProviders.first else { return false } let registeredContentTypes = itemProvider.registeredContentTypes guard let contentType = registeredContentTypes.first else { return false } var suggestedName = itemProvider.suggestedName if suggestedName == nil { switch contentType { case UTType.bmp: suggestedName = "image.bmp" case UTType.gif: suggestedName = "image.gif" case UTType.heic: suggestedName = "image.heic" case UTType.jpeg: suggestedName = "image.jpeg" case UTType.jpegxl: suggestedName = "image.jxl" case UTType.png: suggestedName = "image.png" case UTType.rawImage: suggestedName = "image.raw" case UTType.svg: suggestedName = "image.svg" case UTType.tiff: suggestedName = "image.tiff" case UTType.webP: suggestedName = "image.webp" default: break } } let progress = itemProvider.loadInPlaceFileRepresentation(forTypeIdentifier: contentType.identifier) { url, _, error in if let error { print("Failed to get URL from dropped file: \(error)") return } guard let url else { print("Failed to get URL from dropped file!") return } let queue = OperationQueue() queue.underlyingQueue = .global(qos: .utility) let intent = NSFileAccessIntent.readingIntent(with: url, options: .withoutChanges) let coordinator = NSFileCoordinator() coordinator.coordinate(with: [intent], queue: queue) { error in if let error { print("Failed to coordinate data from dropped file: \(error)") return } do { // Load file contents into Data object let data = try Data(contentsOf: intent.url) Dispatch.DispatchQueue.main.async { self.data.data = data self.data.fileName = suggestedName } } catch { print("Failed to load coordinated data from dropped file: \(error)") } } } DispatchQueue.main.async { self.progress = progress } return true } For your information, this code is at the state where I gave up and sent it here, because I cannot find a solution to my issue. Now, this code works everywhere, except for dragging and dropping from Safari. Let's pretend I go to this web site: https://commons.wikimedia.org/wiki/File:Tulip_Tulipa_clusiana_%27Lady_Jane%27_Rock_Ledge_Flower_Edit_2000px.jpg and I try to drag-and-drop the image, it will fail with the following error: URL https://upload.wikimedia.org/wikipedia/commons/c/cf/Tulip_Tulipa_clusiana_%27Lady_Jane%27_Rock_Ledge_Flower_Edit_2000px.jpg is not a file:// URL. And then, fail with the dreaded Failed to get URL from dropped file: Error Domain=NSItemProviderErrorDomain Code=-1000 As far as I can tell, the problem lies in the opaque NSItemProvider receiving a web site URL from Safari. I tried most solutions, I couldn't retrieve that URL. The error happens in the callback of loadInPlaceFileRepresentation, but also fails in loadFileRepresentation. I tried hard-requesting a loadObject of type URL, but there's only one representation for the JPEG file. I tried only putting .url in the requests, but it would not transfer it. Anyone solved this mystery?

In FileProvider framework based app, is it mandatory to make the host-app sandboxed? I think, no, as Google Drive app is non-sandboxed. But when removing sandboxing from my hostApp, even though mount is visible in Finder but extesnion is not being launched and Finder shows a error message saying "MyApp encountered an error. Items may be out of date." And when I add app-sanboxing, then things work fine. Can someone please help how can we remove sandboxing of hostApp and still make it work. Is there any specific entitlement we need to add, or any whitelisting needed for our Developer Team Id?

Hello, I am currently investigating if we can disable usage of QUIC on application level. I know we can set enable_quic from /Library/Preferences/com.apple.networkd.plist to false but it will have a global impact since this is a system file, all the applications on machine will stop using QUIC. I don't want that. What i am looking for is to disable QUIC only for my application. Is there any way i can modify URLSession object in my application and disable QUIC? or modify URLSessionConfiguration so system will not use QUIC?

I've already searched extensively on Apple Developer Forums and Stack Overflow, and didn't really find what I need or I missed it. I'm developing a macOS music player app that uses cuesheet files paired with audio files. The core functionality is working, opening and playing files works without issues, but I'm struggling with implementing proper file handling features due to my limited experience with UI frameworks. The current state of my app is intentionally simple: Single window interface representing a music player with track list Opening cuesheet files changes the “disc” and updates the window Built with SwiftUI (not AppKit) Not created as a Document-Based app since the user doesn't need to edit, save, or work with multiple documents simultaneously What I Need to Implement: Open Recent menu that actually works Recent files accessible from Dock menu Opening cuesheet files from Finder Drag-and-drop cuesheet files onto app window (lower priority) Problems I've Encountered: I've tried multiple approaches but never achieved full functionality. The closest I got was an “Open Recent” menu that: Only updated after app relaunch Its drop-down kept closing while music was playing My Questions Is it possible purely in SwiftUI? Is there documentation I'm missing? I feel like I might be overcomplicating this. I'm open to alternative approaches if my current direction isn't ideal: Should I redesign as Document-Based? Since I apparently need NSDocumentController, would it be better to start with a Document-Based app template and disable unwanted features, and how? Should I mix AppKit with SwiftUI? While SwiftUI has been wonderful for my main window, it's becoming frustrating for other UI parts, especially menus. Would using AppKit for menus and keeping SwiftUI for the main interface be a reasonable approach? I thought this would be straightforward: Customize the .fileImporter with the proper logic of what to do with the files Call NSDocumentController.shared.noteNewRecentDocumentURL(url) so the Open Recent menu is created a populated with opened files. Maybe it really is that simple and I've gotten lost down a rabbit hole? UI programming is quite new to me, so I might be missing something obvious. Any guidance, code examples, or pointing me toward the right documentation would be greatly appreciated!