immich-app/immich · warning · BadRequestException

Unsupported file type

Error message

Unsupported file type ${filename}

What it means

canUploadFile validates an upload's file extension against the server's allowlist of supported media types (photos, videos, sidecar files). If the filename's extension matches no configured group, it logs and throws a BadRequestException naming the offending file. This is Immich's gate against accepting files it cannot process or store meaningfully.

Solutions

1. Remove or convert the file to a supported format (JPEG, PNG, HEIC, MP4, MOV, etc.) before uploading.
2. Check server settings: some formats can be enabled in the asset/video transcoding or upload configuration.
3. If you control the client, filter the file list by extension before calling the upload API.
4. Rename the file with a correct extension if it was saved with a wrong/missing one and the content is actually a supported media type.

Example fix

// before
await immichApi.uploadFile({ file: new File([data], 'notes.txt') });
// after
const SUPPORTED = /\.(jpe?g|png|gif|webp|heic|heif|avif|mp4|mov|avi|mkv)$/i;
if (!SUPPORTED.test(file.name)) throw new Error(`Skipping unsupported file: ${file.name}`);
await immichApi.uploadFile({ file });

const SUPPORTED = /\.(jpe?g|png|gif|webp|heic|heif|avif|dng|mp4|mov|avi|mkv|webm)$/i;
if (!SUPPORTED.test(file.name)) throw new Error(`Unsupported file type: ${file.name}`);

try { await upload(file); } catch (e) { if (String(e).includes('Unsupported file type')) skipAndLog(file); else throw e; }

When it happens

Trigger: Calling POST /api/assets (uploadAsset) with a file whose extension is not in any supported-extension list, e.g. .heic when unsupported, .txt, .pdf, .exe, or an extension-less filename.

Common situations: Uploading documents or RAW formats not yet supported; users sharing miscellaneous files through Immich; files saved by cameras/apps with unusual extensions; reverse proxies stripping or mangling the original filename.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• assetIds, albumId, or userId is required
• At least two people are required for merging
• Cannot request to join your own cluster group
• error instanceof Error ? error.message : error
• {error.message}

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

Appendix: source

Thrown at server/src/services/asset-media.service.ts:88

      }

      case UploadFieldName.SIDECAR_DATA: {
        if (mimeTypes.isSidecar(filename)) {
          return true;
        }
        break;
      }

      case UploadFieldName.PROFILE_DATA: {
        if (mimeTypes.isProfile(filename)) {
          return true;
        }
        break;
      }
    }

    this.logger.error(`Unsupported file type ${filename}`);
    throw new BadRequestException(`Unsupported file type ${filename}`);
  }

  getUploadFilename({ auth, fieldName, file, body }: UploadRequest): string {
    requireUploadAccess(auth);

    const extension = getFilenameExtension(body.filename || file.originalName);
    const lookup = {
      [UploadFieldName.ASSET_DATA]: extension,
      [UploadFieldName.SIDECAR_DATA]: '.xmp',
      [UploadFieldName.PROFILE_DATA]: extension,
    };

    return sanitize(`${file.uuid}${lookup[fieldName]}`);
  }

  getUploadFolder({ auth, fieldName, file }: UploadRequest): string {
    auth = requireUploadAccess(auth);

View on GitHub (pinned to e55ac299a4)