{"record":{"id":"934cfb008bdc9ffd","repo":"koodo-reader/koodo-reader","slug":"file-system-access-api-not-supported","errorCode":null,"errorMessage":"File System Access API not supported","messagePattern":"File System Access API not supported","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/utils/file/localFile.ts","lineNumber":78,"sourceCode":"        // Fallback: try to read a property; may still throw for invalid handle\n        void handle.name;\n      }\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  // 检查浏览器是否支持 File System Access API\n  static isSupported(): boolean {\n    return \"showDirectoryPicker\" in window;\n  }\n\n  // 请求目录访问权限\n  static async requestDirectoryAccess(): Promise<FileSystemDirectoryHandle | null> {\n    try {\n      if (!this.isSupported()) {\n        throw new Error(\"File System Access API not supported\");\n      }\n\n      const directoryHandle = await (window as any).showDirectoryPicker({\n        mode: \"readwrite\",\n        startIn: \"documents\",\n      });\n\n      // 存储权限句柄到 IndexedDB\n      await this.storeDirectoryHandle(directoryHandle);\n      this.directoryHandle = directoryHandle;\n\n      return directoryHandle;\n    } catch (error) {\n      console.error(\"Error requesting directory access:\", error);\n      return null;\n    }\n  }\n  // 添加用户友好的权限状态检查方法","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/koodo-reader/koodo-reader/blob/7d40df41e05cfc0a341fe9ea66a12819b522b7fa/src/utils/file/localFile.ts#L60-L96","documentation":"LocalFileService wraps the browser File System Access API for storing books/covers locally. requestDirectoryAccess() throws 'File System Access API not supported' when window.showDirectoryPicker is undefined, i.e. the runtime does not implement the API (isSupported() is false). It is thrown inside the try block, so callers receive it as a rejection rather than a null handle.","triggerScenarios":"Calling requestDirectoryAccess() in Firefox/Safari (no showDirectoryPicker), in mobile browsers, in non-secure contexts (the API requires HTTPS or localhost), or in Electron/iframe environments where the picker is unavailable.","commonSituations":"Users on Firefox or Safari trying to enable local storage sync, deploying the app over plain HTTP so secure-context-only APIs are hidden, or embedded webviews lacking the picker.","solutions":["Feature-detect with LocalFileService.isSupported() (or 'showDirectoryPicker' in window) before calling and show a fallback UI for unsupported browsers","Serve the app over HTTPS or localhost so secure-context APIs are exposed","In unsupported browsers, fall back to download/upload-based workflows or IndexedDB storage","If in Electron, ensure the Chromium version is recent enough to include showDirectoryPicker"],"exampleFix":"// before\nconst handle = await LocalFileService.requestDirectoryAccess();\n// after\nif (!LocalFileService.isSupported()) {\n  alert(\"Your browser does not support local directory access.\");\n} else {\n  const handle = await LocalFileService.requestDirectoryAccess();\n}","handlingStrategy":"fallback","validationCode":"if (!(\"showDirectoryPicker\" in window)) {\n  // unsupported — route to fallback UI\n}\nif (!window.isSecureContext) {\n  // API hidden on insecure origins\n}","typeGuard":"function supportsFileSystemAccess(w: Window = window): w is Window & { showDirectoryPicker: (o?: any) => Promise<FileSystemDirectoryHandle> } {\n  return \"showDirectoryPicker\" in w;\n}","tryCatchPattern":"try {\n  const handle = await LocalFileService.requestDirectoryAccess();\n} catch (e) {\n  if (e.message === \"File System Access API not supported\") {\n    enableFallbackStorage(); // download/upload or IndexedDB mode\n  } else throw e;\n}","preventionTips":["Feature-detect showDirectoryPicker before exposing local-storage features","Serve over HTTPS or localhost (secure context required)","Maintain a browser support matrix (Chrome/Edge yes; Firefox/Safari no) and test it","Offer a non-API fallback storage mode in settings"],"tags":["browser-compatibility","file-system-access-api","feature-detection"],"backgroundTag":"api-not-supported-in-browser","analyzedSha":"7d40df41e05cfc0a341fe9ea66a12819b522b7fa","analyzedAt":"2026-08-29T01:41:43.691Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}