{"record":{"id":"320797b9c67c83fc","repo":"AvaloniaUI/Avalonia","slug":"storageitem-is-not-a-file","errorCode":null,"errorMessage":"StorageItem is not a file","messagePattern":"StorageItem is not a file","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/Browser/Avalonia.Browser/webapp/modules/storage/storageItem.ts","lineNumber":52,"sourceCode":"    public static createFromHandle(handle: FileSystemFileHandle | FileSystemDirectoryHandle, bookmarkId?: string) {\n        return new StorageItem(handle, undefined, bookmarkId, undefined);\n    }\n\n    public static createFromFile(file: File) {\n        return new StorageItem(undefined, file, undefined, undefined);\n    }\n\n    public static createWellKnownDirectory(type: WellKnownDirectory) {\n        return new StorageItem(undefined, undefined, undefined, type);\n    }\n\n    public static async openRead(item: StorageItem): Promise<Blob> {\n        if (item.file) {\n            return item.file;\n        }\n\n        if (!item.handle || item.kind !== \"file\") {\n            throw new Error(\"StorageItem is not a file\");\n        }\n\n        await item.verifyPermissions(\"read\");\n\n        const file = await (item.handle as FileSystemFileHandle).getFile();\n        return file;\n    }\n\n    public static async openWrite(item: StorageItem): Promise<FileSystemWritableFileStream> {\n        if (!item.handle || item.kind !== \"file\") {\n            throw new Error(\"StorageItem is not a writeable file\");\n        }\n\n        await item.verifyPermissions(\"readwrite\");\n\n        return await (item.handle as FileSystemFileHandle).createWritable({ keepExistingData: false });\n    }\n","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/AvaloniaUI/Avalonia/blob/11c542726898ae954a1ef668c65ec79ec92ab17d/src/Browser/Avalonia.Browser/webapp/modules/storage/storageItem.ts#L34-L70","documentation":"Thrown by StorageItem.openRead when the item has no FileSystemFileHandle or its kind is not 'file'. openRead needs a real file handle (or a pre-attached File) to call getFile() and return its Blob; a directory or a handleless item cannot be read.","triggerScenarios":"StorageItem.openRead(item) where item.handle is undefined AND item.file is undefined (so the early return on item.file is skipped), or item.kind === 'directory'. Calling openRead on a directory StorageItem or on a well-known-directory placeholder created via createWellKnownDirectory.","commonSituations":"User code passes a folder handle to a file-read API; a StorageItem built from createWellKnownDirectory (which has no handle/file) is misused for reading; a directory entry from getItemsIterator is handed to openRead.","solutions":["Check item.kind === 'file' and item.handle (or item.file) before calling openRead.","Obtain the item via getFile (directory.getFileHandle) rather than getFolder for files you intend to read.","Filter directory entries out of iteration before attempting reads."],"exampleFix":"// before\nconst blob = await StorageItem.openRead(item); // item is a directory\n\n// after\nif (item.kind !== 'file') throw new Error('expected a file item');\nconst blob = await StorageItem.openRead(item);","handlingStrategy":"type-guard","validationCode":"if (!item.file && (!item.handle || item.kind !== 'file')) {\n  throw new Error('StorageItem is not a file; cannot openRead');\n}","typeGuard":"function isReadableFileItem(item: StorageItem): boolean {\n  return item.kind === 'file' && (!!item.file || !!item.handle);\n}","tryCatchPattern":"try { return await StorageItem.openRead(item); }\ncatch (e) {\n  if (e instanceof Error && e.message === 'StorageItem is not a file') { /* prompt user to pick a file */ return null; }\n  throw e;\n}","preventionTips":["Filter directory entries out before calling openRead.","Use getFile (not getFolder) to obtain file items.","Distinguish File-backed items from handle-backed items."],"tags":["browser","storage","file-system-access","typescript","validation"],"backgroundTag":null,"analyzedSha":"11c542726898ae954a1ef668c65ec79ec92ab17d","analyzedAt":"2026-08-13T11:57:40.261Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}