{"record":{"id":"c86aae6c7152ff4f","repo":"immich-app/immich","slug":"failed-to-create-externalpath-docsmessage","errorCode":null,"errorMessage":"Failed to create \"${externalPath} - ${docsMessage}\"","messagePattern":"Failed to create \"(.+?) - (.+?)\"","errorType":"exception","errorClass":"ImmichStartupError","httpStatus":null,"severity":"critical","filePath":"server/src/services/storage.service.ts","lineNumber":176,"sourceCode":"      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\n  private async verifyWriteAccess(folder: StorageFolder) {\n    const { internalPath, externalPath } = this.getMountFilePaths(folder);\n    try {\n      await this.storageRepository.overwriteFile(internalPath, Buffer.from(Date.now().toString()));\n    } catch (error) {\n      this.logger.error(`Failed to write ${internalPath}: ${error}`);\n      throw new ImmichStartupError(`Failed to write \"${externalPath} - ${docsMessage}\"`);\n    }\n  }\n\n  private getMountFilePaths(folder: StorageFolder) {\n    const folderPath = StorageCore.getBaseFolder(folder);\n    const internalPath = join(folderPath, '.immich');\n    const externalPath = `<UPLOAD_LOCATION>/${folder}/.immich`;\n","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/storage.service.ts#L158-L194","documentation":"During bootstrap, Immich creates a mount-check file per storage folder to validate write access; if creation fails with an error other than EEXIST, it raises an ImmichStartupError naming the external path, because Immich cannot write to the configured storage location.","triggerScenarios":"Starting Immich when the storage folder is read-only, the volume is mounted but the process user lacks write permission, or the folder doesn't exist and cannot be created.","commonSituations":"Bind mounts owned by root while Immich runs as another UID; read-only volume mounts (':ro'); disk-full or NFS with root-squash; missing host directory in docker-compose so Docker creates a root-owned folder.","solutions":["Fix ownership/permissions so the Immich user can write: chown -R <uid>:<gid> on the data directory (commonly 1000:1000).","Remove ':ro' from the volume mount if present and remount the volume read-write.","Pre-create the host folder with correct ownership so Docker doesn't create it as root.","Check disk space / mount health (df -h, mount status) if permissions look correct."],"exampleFix":"// before (docker-compose.yml)\nvolumes:\n  - ./upload:/usr/src/app/upload:ro\n// after\nvolumes:\n  - ./upload:/usr/src/app/upload\n// plus: chown -R 1000:1000 ./upload","handlingStrategy":"try-catch","validationCode":"// before starting, verify each storage folder is writable by the immich user\nimport { accessSync, constants } from 'node:fs';\nfor (const dir of storageFolders) accessSync(dir, constants.W_OK);","typeGuard":null,"tryCatchPattern":"try {\n  await startImmichServer();\n} catch (e) {\n  if (/Failed to create \\\"/.test(String(e.message))) {\n    // fix ownership/permissions or read-only mount, then restart\n    process.exit(1);\n  } else throw e;\n}","preventionTips":["Pre-create host folders with correct UID/GID ownership (e.g. 1000:1000)","Never mount storage folders read-only","Avoid NFS root-squash mismatches for the data volume","Check disk space and mount writability in deployment checks"],"tags":["immich","storage","startup","permissions","filesystem"],"backgroundTag":"file-write-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"}