{"record":{"id":"2cf457d1bc04a671","repo":"AvaloniaUI/Avalonia","slug":"storageitem-is-not-a-writeable-file","errorCode":null,"errorMessage":"StorageItem is not a writeable file","messagePattern":"StorageItem is not a writeable file","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/Browser/Avalonia.Browser/webapp/modules/storage/storageItem.ts","lineNumber":63,"sourceCode":"\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\n    public static async getProperties(item: StorageItem): Promise<{ Size: number; LastModified: number; Type: string } | null> {\n        // getFile can fail with an exception depending if we use polyfill with a save file dialog or not.\n        try {\n            const file = item.handle && \"getFile\" in item.handle\n                ? await item.handle.getFile()\n                : item.file;\n\n            if (!file) {\n                return null;\n            }\n","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/AvaloniaUI/Avalonia/blob/11c542726898ae954a1ef668c65ec79ec92ab17d/src/Browser/Avalonia.Browser/webapp/modules/storage/storageItem.ts#L45-L81","documentation":"Thrown by StorageItem.openWrite when the item has no handle or its kind is not 'file'. Writing requires a FileSystemFileHandle to call createWritable; a directory or a handleless item (e.g. a raw File or a well-known directory) is not writeable.","triggerScenarios":"StorageItem.openWrite(item) where item.handle is undefined or item.kind !== 'file'. Most commonly calling openWrite on a StorageItem created from createFromFile (a read-only File with no handle) or on a directory item.","commonSituations":"Trying to save back to a File picked from an <input type=file> (no FileSystemFileHandle, so not writeable); writing to a directory handle; using the polyfill path where no native picker/granted handle exists.","solutions":["Acquire the item via the native file picker (showSaveFilePicker) so it carries a FileSystemFileHandle before writing.","Guard with item.kind === 'file' && !!item.handle before openWrite.","When the user must overwrite an existing picked File, prompt with showSaveFilePicker to get a writable handle."],"exampleFix":"// before\nconst writable = await StorageItem.openWrite(item); // item from <input type=file>\n\n// after\nif (!item.handle || item.kind !== 'file') {\n  const handle = await window.showSaveFilePicker();\n  item = StorageItem.createFromHandle(handle);\n}\nconst writable = await StorageItem.openWrite(item);","handlingStrategy":"validation","validationCode":"if (!item.handle || item.kind !== 'file') {\n  // acquire a writable handle via the native picker instead\n  const handle = await window.showSaveFilePicker();\n  item = StorageItem.createFromHandle(handle);\n}","typeGuard":"function isWriteableFileItem(item: StorageItem): boolean {\n  return item.kind === 'file' && !!item.handle;\n}","tryCatchPattern":"try { return await StorageItem.openWrite(item); }\ncatch (e) {\n  if (e instanceof Error && e.message.includes('writeable file')) { /* re-prompt for a save handle */ return null; }\n  throw e;\n}","preventionTips":["Do not expect File objects from <input type=file> to be writeable.","Acquire FileSystemFileHandle via showSaveFilePicker for writing.","Guard kind/handle before openWrite."],"tags":["browser","storage","file-system-access","typescript","validation","write"],"backgroundTag":null,"analyzedSha":"11c542726898ae954a1ef668c65ec79ec92ab17d","analyzedAt":"2026-08-13T11:57:40.261Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}