{"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/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/storage.service.ts#L158-L194","documentation":"Thrown by StorageService.createMountFile at startup when mkdir of the folder path or creation of the '.immich' marker file fails with an errno other than EEXIST (EEXIST is tolerated). It aborts boot via ImmichStartupError, including the external path and the folder-checks doc link.","triggerScenarios":"Server boot, folder-integrity phase: storageRepository.mkdirSync(folderPath) or createFile(internalPath, ...) throws a non-EEXIST error (e.g. EACCES, ENOSPC, EROFS).","commonSituations":"Disk full on the volume backing the upload/library folder; read-only filesystem (read-only bind mount or read-only rootfs); SELinux/AppCore denying write; parent directory missing because a prior mount step failed.","solutions":["Free space on the target volume and retry boot.","Confirm the bind mount is not ':ro' and the immich uid has write permission to the folder.","Create the parent directory on the host if it is missing, then restart.","On SELinux-enabled hosts, relabel the mount: chcon -Rt container_file_t <host path>.","Inspect the prior log line 'Failed to create <internalPath>: <error>' for the exact errno."],"exampleFix":"chmod -R u+rwX /mnt/immich/upload && chown -R 1000:1000 /mnt/immich/upload","handlingStrategy":"validation","validationCode":"import { accessSync, constants, mkdirSync } from 'node:fs';\n\nfunction ensureWritableDir(p: string) {\n  mkdirSync(p, { recursive: true });\n  accessSync(p, constants.W_OK | constants.X_OK);\n}\n// call ensureWritableDir(folderPath) for each StorageFolder before boot","typeGuard":null,"tryCatchPattern":"try { await storageService.onBootstrap(); }\ncatch (e) {\n  if (e instanceof ImmichStartupError && /Failed to create/.test(e.message)) {\n    // check disk space & permissions, then restart - do not loop\n  }\n}","preventionTips":["Alert on free space < 5% on volumes backing upload/library/encoded folders.","Avoid ':ro' bind mounts for any Immich-managed folder.","On SELinux hosts, label host paths with container_file_t before first boot."],"tags":["storage","startup","filesystem","permissions","disk-space"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}