unoplatform/uno · error · Error

Item ${guid} is a directory handle. You cannot use it as a F

Error message

Item ${guid} is a directory handle. You cannot use it as a File!

What it means

Thrown by NativeStorageItem.getFile when the item stored under the given guid is a FileSystemDirectoryHandle (a folder) rather than a file. The getFile method is meant to resolve a File; passing a directory handle is a type mismatch — directories cannot be read as files.

Source

Thrown at src/Uno.UWP/ts/Windows/Storage/NativeStorageItem.ts:33

			NativeStorageItem._guidToItemMap.delete(guid);
			NativeStorageItem._itemToGuidMap.delete(handle);
		}

		public static getItem(guid: string): FileSystemHandle|File {
			return NativeStorageItem._guidToItemMap.get(guid);
		}

		public static async getFile(guid: string): Promise<File> {
			const item = NativeStorageItem.getItem(guid);

			if (item instanceof File) {
				return item as File;
			}
			if (item instanceof FileSystemFileHandle) {
				return await (item as FileSystemFileHandle).getFile();
			}
			if (item instanceof FileSystemDirectoryHandle) {
				throw new Error("Item " + guid + " is a directory handle. You cannot use it as a File!");
			}

			throw new Error("Item " + guid + " is of an unknown type. You cannot use it as a File!");
		}

		public static getGuid(item: FileSystemHandle | File): string {
			return NativeStorageItem._itemToGuidMap.get(item);
		}

		public static getInfos(...items: Array<FileSystemHandle|File>): NativeStorageItemInfo[] {
			const itemsWithoutGuids: Array<FileSystemHandle|File> = [];

			for (const item of items) {
				const guid = NativeStorageItem.getGuid(item);
				if (!guid) {
					itemsWithoutGuids.push(item);
				}
			}

View on GitHub (pinned to 0418340488)

Solutions

1. Check the item kind before calling getFile: use getInfos or inspect whether the handle is a file vs directory.
2. Handle directory drops separately using the StorageFolder / directory handle path instead of getFile.
3. Filter drop items so only file-kind items reach getFile.

Example fix

// before: unconditionally call getFile
const file = await NativeStorageItem.getFile(guid);

// after: check kind first
const item = NativeStorageItem.getItem(guid);
if (item instanceof FileSystemDirectoryHandle) {
    // handle as folder
} else {
    const file = await NativeStorageItem.getFile(guid);
}

const item = NativeStorageItem.getItem(guid);
if (item instanceof FileSystemDirectoryHandle) {
    // do not call getFile — handle as folder
}

function isFileItem(item: unknown): item is File | FileSystemFileHandle {
    return item instanceof File || item instanceof FileSystemFileHandle;
}

try {
    const file = await NativeStorageItem.getFile(guid);
} catch (e) {
    if (e.message.includes('directory handle')) {
        // user dropped a folder — handle via StorageFolder path
    } else { throw e; }
}

When it happens

Trigger: The managed code called getFile(guid) on a guid that was registered via addItem for a FileSystemDirectoryHandle — e.g. a user dragged a folder onto the app and the code attempted to open it as a file stream.

Common situations: Drag-and-drop of a directory onto a file-only drop target; the managed StorageFile abstraction was used for what is actually a StorageFolder; a guid mix-up where a folder guid was passed to a file-access API.

Related errors

• Item ${guid} is of an unknown type. You cannot use it as a F
• retrieveFiles failed to find pending drag and drop data for
• A DragDropExtension has already been enabled
• The current DragDropExtension does not match the provided ar
• No pending drag and drop data.

AI-assisted analysis of unoplatform/uno@0418340488 (2026-08-13). Data as JSON: /api/errors/8092193508342127. Report an issue: GitHub.