{"record":{"id":"8092193508342127","repo":"unoplatform/uno","slug":"item-guid-is-a-directory-handle-you-cannot-use","errorCode":null,"errorMessage":"Item ${guid} is a directory handle. You cannot use it as a File!","messagePattern":"Item (.+?) is a directory handle\\. You cannot use it as a File!","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/Uno.UWP/ts/Windows/Storage/NativeStorageItem.ts","lineNumber":33,"sourceCode":"\t\t\tNativeStorageItem._guidToItemMap.delete(guid);\n\t\t\tNativeStorageItem._itemToGuidMap.delete(handle);\n\t\t}\n\n\t\tpublic static getItem(guid: string): FileSystemHandle|File {\n\t\t\treturn NativeStorageItem._guidToItemMap.get(guid);\n\t\t}\n\n\t\tpublic static async getFile(guid: string): Promise<File> {\n\t\t\tconst item = NativeStorageItem.getItem(guid);\n\n\t\t\tif (item instanceof File) {\n\t\t\t\treturn item as File;\n\t\t\t}\n\t\t\tif (item instanceof FileSystemFileHandle) {\n\t\t\t\treturn await (item as FileSystemFileHandle).getFile();\n\t\t\t}\n\t\t\tif (item instanceof FileSystemDirectoryHandle) {\n\t\t\t\tthrow new Error(\"Item \" + guid + \" is a directory handle. You cannot use it as a File!\");\n\t\t\t}\n\n\t\t\tthrow new Error(\"Item \" + guid + \" is of an unknown type. You cannot use it as a File!\");\n\t\t}\n\n\t\tpublic static getGuid(item: FileSystemHandle | File): string {\n\t\t\treturn NativeStorageItem._itemToGuidMap.get(item);\n\t\t}\n\n\t\tpublic static getInfos(...items: Array<FileSystemHandle|File>): NativeStorageItemInfo[] {\n\t\t\tconst itemsWithoutGuids: Array<FileSystemHandle|File> = [];\n\n\t\t\tfor (const item of items) {\n\t\t\t\tconst guid = NativeStorageItem.getGuid(item);\n\t\t\t\tif (!guid) {\n\t\t\t\t\titemsWithoutGuids.push(item);\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/unoplatform/uno/blob/04183404888ea21b4e5bfa3493e8d5f15e972c3a/src/Uno.UWP/ts/Windows/Storage/NativeStorageItem.ts#L15-L51","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the item kind before calling getFile: use getInfos or inspect whether the handle is a file vs directory.","Handle directory drops separately using the StorageFolder / directory handle path instead of getFile.","Filter drop items so only file-kind items reach getFile."],"exampleFix":"// before: unconditionally call getFile\nconst file = await NativeStorageItem.getFile(guid);\n\n// after: check kind first\nconst item = NativeStorageItem.getItem(guid);\nif (item instanceof FileSystemDirectoryHandle) {\n    // handle as folder\n} else {\n    const file = await NativeStorageItem.getFile(guid);\n}","handlingStrategy":"type-guard","validationCode":"const item = NativeStorageItem.getItem(guid);\nif (item instanceof FileSystemDirectoryHandle) {\n    // do not call getFile — handle as folder\n}","typeGuard":"function isFileItem(item: unknown): item is File | FileSystemFileHandle {\n    return item instanceof File || item instanceof FileSystemFileHandle;\n}","tryCatchPattern":"try {\n    const file = await NativeStorageItem.getFile(guid);\n} catch (e) {\n    if (e.message.includes('directory handle')) {\n        // user dropped a folder — handle via StorageFolder path\n    } else { throw e; }\n}","preventionTips":["Filter drag-drop items by kind before routing to getFile vs folder APIs.","Use getInfos to check isFile before attempting getFile.","Handle directory drops with a separate code path."],"tags":["wasm","storage","file-system-access","drag-and-drop","typescript"],"backgroundTag":null,"analyzedSha":"04183404888ea21b4e5bfa3493e8d5f15e972c3a","analyzedAt":"2026-08-13T21:08:11.651Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}