{"record":{"id":"aae08140849adcf4","repo":"immich-app/immich","slug":"asset-assetid-has-transparency-but-the-configured-format-is","errorCode":null,"errorMessage":"Asset ${assetId} has transparency but the configured format is ${format} which does not support it, consider using a format that does, such as ${ImageFormat.Webp}","messagePattern":"Asset (.+?) has transparency but the configured format is (.+?) which does not support it, consider using a format that does, such as (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"info","filePath":"server/src/services/media.service.ts","lineNumber":851,"sourceCode":"        }\n      : undefined;\n\n    const originalDimensions = getDimensions(asset.exifInfo!);\n    const assetFaces = await this.personRepository.getFaces(asset.id, { viewingUserId: asset.ownerId });\n    const ocrData = await this.ocrRepository.getByAssetId(asset.id, {});\n\n    const faceStatuses = checkFaceVisibility(assetFaces, originalDimensions, cropBox);\n    await this.personRepository.updateVisibility(faceStatuses.visible, faceStatuses.hidden);\n\n    const ocrStatuses = checkOcrVisibility(ocrData, originalDimensions, cropBox);\n    await this.ocrRepository.updateOcrVisibilities(asset.id, ocrStatuses.visible, ocrStatuses.hidden);\n\n    return generated;\n  }\n\n  private warnOnTransparencyLoss(isTransparent: boolean, format: ImageFormat, assetId: string) {\n    if (isTransparent && format === ImageFormat.Jpeg) {\n      this.logger.warn(\n        `Asset ${assetId} has transparency but the configured format is ${format} which does not support it, consider using a format that does, such as ${ImageFormat.Webp}`,\n      );\n    }\n  }\n\n  private getImageFile(\n    asset: ThumbnailPathEntity,\n    options: ImagePathOptions & { isProgressive: boolean; isTransparent: boolean },\n  ) {\n    const path = StorageCore.getImagePath(asset, options);\n    return {\n      assetId: asset.id,\n      type: options.fileType,\n      path,\n      isEdited: options.isEdited,\n      isProgressive: options.isProgressive,\n      isTransparent: options.isTransparent,\n    };","sourceCodeStart":833,"sourceCodeEnd":869,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/media.service.ts#L833-L869","documentation":"When configured thumbnail/image format is JPEG, transparency (alpha channel) cannot be preserved. This warning notifies the operator that a transparent asset (e.g. PNG/WebP with alpha) will lose its transparency when converted, and suggests switching to a format that supports alpha such as WebP.","triggerScenarios":"warnOnTransparencyLoss is called during image thumbnail generation with isTransparent=true and format=ImageFormat.Jpeg — i.e. the server's image.thumbnail.format (or preview format) setting is JPEG while processing a transparent image.","commonSituations":"Uploading PNG/transparent WebP stickers or logos while the default JPEG thumbnail format is configured; admin never changed the default format; mixed libraries with a few transparent assets.","solutions":["Change the thumbnail/preview image format to webp in Administration > Settings > Image (thumbnail) settings","Accept the warning if opaque thumbnails are fine; transparency is flattened onto the background","Convert the source asset to an opaque format if transparency is unwanted anyway","No action needed for photos; this only matters for graphics with alpha"],"exampleFix":"// before\n// thumbnail.format = 'jpeg' (config)\n// after\n// thumbnail.format = 'webp'  # supports alpha, silences the warning","handlingStrategy":"validation","validationCode":"if (isTransparent && format === ImageFormat.Jpeg) {\n  logger.warn('Transparency will be lost; consider format=webp');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set thumbnail/preview format to webp if your library contains PNG/alpha graphics","Treat this warning as a config hint, not a failure","Audit image format settings after upgrades","Check assets for alpha channels when importing graphic-heavy libraries"],"tags":["thumbnails","image-format","transparency"],"backgroundTag":"invalid-config-value","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"}