{"record":{"id":"709b90fb818390d5","repo":"immich-app/immich","slug":"failed-to-read-externalpath-internalpath","errorCode":null,"errorMessage":"Failed to read: \"${externalPath} (${internalPath}) - ${docsMessage}\"","messagePattern":"Failed to read: \"(.+?) \\((.+?)\\) - (.+?)\"","errorType":"exception","errorClass":"ImmichStartupError","httpStatus":null,"severity":"critical","filePath":"server/src/services/storage.service.ts","lineNumber":161,"sourceCode":"      }\n\n      try {\n        await this.storageRepository.unlink(file);\n      } catch (error: any) {\n        this.logger.warn('Unable to remove file from disk', error);\n      }\n    }\n\n    return JobStatus.Success;\n  }\n\n  private async verifyReadAccess(folder: StorageFolder) {\n    const { internalPath, externalPath } = this.getMountFilePaths(folder);\n    try {\n      await this.storageRepository.readFile(internalPath);\n    } catch (error) {\n      this.logger.error(`Failed to read (${internalPath}): ${error}`);\n      throw new ImmichStartupError(`Failed to read: \"${externalPath} (${internalPath}) - ${docsMessage}\"`);\n    }\n  }\n\n  private async createMountFile(folder: StorageFolder) {\n    const { folderPath, internalPath, externalPath } = this.getMountFilePaths(folder);\n    try {\n      this.storageRepository.mkdirSync(folderPath);\n      await this.storageRepository.createFile(internalPath, Buffer.from(Date.now().toString()));\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {\n        this.logger.warn('Found existing mount file, skipping creation');\n        return;\n      }\n      this.logger.error(`Failed to create ${internalPath}: ${error}`);\n      throw new ImmichStartupError(`Failed to create \"${externalPath} - ${docsMessage}\"`);\n    }\n  }\n","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/storage.service.ts#L143-L179","documentation":"During bootstrap, Immich verifies it can read a mount-check file inside each configured storage folder; if readFile on the internal path fails, it raises an ImmichStartupError naming the external path, because the storage location is not usable (missing volume, permissions, or wrong mount).","triggerScenarios":"Starting Immich when the upload/library volume is not mounted, the folder or .immich mount file is missing, or the process lacks read permission on the internal path.","commonSituations":"Docker volume failed to mount (host path absent); permissions changed on the host directory; NFS/network mount offline at startup; internal/external path mapping wrong for the storage folder.","solutions":["Verify the volume is mounted and contains the data (docker inspect / ls the host path) and start the mount before Immich.","Fix filesystem permissions so the Immich process user can read the folder (chown/chmod the data directory).","Check the internal/external path mapping (IMMICH_MEDIA_LOCATION / storage folder config) points at the real mounted directory.","Recreate the missing mount check file (.immich) if the folder exists but the file was deleted, after confirming the mount is correct."],"exampleFix":"// before (docker-compose.yml)\nvolumes:\n  - ./upload:/usr/src/app/upload\n// after — ensure the host dir exists with correct ownership\n// $ mkdir -p ./upload && chown -R 1000:1000 ./upload\nvolumes:\n  - ./upload:/usr/src/app/upload","handlingStrategy":"try-catch","validationCode":"// before starting, verify each storage folder is readable by the immich user\nimport { accessSync, constants } from 'node:fs';\nfor (const dir of storageFolders) accessSync(dir, constants.R_OK);","typeGuard":null,"tryCatchPattern":"try {\n  await startImmichServer();\n} catch (e) {\n  if (/Failed to read:/.test(String(e.message))) {\n    // check volume mount, permissions, and IMMICH_MEDIA_LOCATION mapping, then restart\n    process.exit(1);\n  } else throw e;\n}","preventionTips":["Ensure volumes are mounted before the server starts (healthcheck/depends_on)","Run Immich as a user with read access to all storage folders","Verify internal vs external path mappings after image upgrades","Monitor mounts (NFS/CIFS) for availability at boot"],"tags":["immich","storage","startup","filesystem","permissions"],"backgroundTag":"file-read-failed","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}