immich-app/immich · info

Asset has transparency but the configured format is which…

Error message

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}

What it means

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.

Solutions

1. Change the thumbnail/preview image format to webp in Administration > Settings > Image (thumbnail) settings
2. Accept the warning if opaque thumbnails are fine; transparency is flattened onto the background
3. Convert the source asset to an opaque format if transparency is unwanted anyway
4. No action needed for photos; this only matters for graphics with alpha

Example fix

// before
// thumbnail.format = 'jpeg' (config)
// after
// thumbnail.format = 'webp'  # supports alpha, silences the warning

if (isTransparent && format === ImageFormat.Jpeg) {
  logger.warn('Transparency will be lost; consider format=webp');
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Skipping thumbnail generation for asset
• Thumbnail generation failed for asset

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/aae08140849adcf4. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/media.service.ts:851

        }
      : undefined;

    const originalDimensions = getDimensions(asset.exifInfo!);
    const assetFaces = await this.personRepository.getFaces(asset.id, { viewingUserId: asset.ownerId });
    const ocrData = await this.ocrRepository.getByAssetId(asset.id, {});

    const faceStatuses = checkFaceVisibility(assetFaces, originalDimensions, cropBox);
    await this.personRepository.updateVisibility(faceStatuses.visible, faceStatuses.hidden);

    const ocrStatuses = checkOcrVisibility(ocrData, originalDimensions, cropBox);
    await this.ocrRepository.updateOcrVisibilities(asset.id, ocrStatuses.visible, ocrStatuses.hidden);

    return generated;
  }

  private warnOnTransparencyLoss(isTransparent: boolean, format: ImageFormat, assetId: string) {
    if (isTransparent && format === ImageFormat.Jpeg) {
      this.logger.warn(
        `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}`,
      );
    }
  }

  private getImageFile(
    asset: ThumbnailPathEntity,
    options: ImagePathOptions & { isProgressive: boolean; isTransparent: boolean },
  ) {
    const path = StorageCore.getImagePath(asset, options);
    return {
      assetId: asset.id,
      type: options.fileType,
      path,
      isEdited: options.isEdited,
      isProgressive: options.isProgressive,
      isTransparent: options.isTransparent,
    };

View on GitHub (pinned to e55ac299a4)