immich-app/immich · error · BadRequestException

SyncRequestType.AlbumAssetsV1 is deprecated, use SyncRequest

Error message

SyncRequestType.AlbumAssetsV1 is deprecated, use SyncRequestType.AlbumAssetsV2 instead

What it means

Thrown (as BadRequestException) by SyncService.syncAlbumAssetsV1, a stub that always rejects. AlbumAssetsV1 is replaced by AlbumAssetsV2 (which includes the AlbumAssetBackfillV2 flow) and the old stream is disabled.

Source

Thrown at server/src/services/sync.service.ts:524

        sendEntityBackfillCompleteAck(response, backfillType, createId);
      }
    } else if (albums.length > 0) {
      await this.upsertBackfillCheckpoint({
        type: backfillType,
        sessionId,
        createId: albums.at(-1)!.createId,
      });
    }

    const upserts = this.syncRepository.albumUser.getUpserts({ ...options, ack: checkpointMap[upsertType] });
    for await (const { updateId, ...data } of upserts) {
      send(response, { type: upsertType, ids: [updateId], data });
    }
  }

  private syncAlbumAssetsV1(): Promise<void> {
    throw new BadRequestException(
      'SyncRequestType.AlbumAssetsV1 is deprecated, use SyncRequestType.AlbumAssetsV2 instead',
    );
  }

  private async syncAlbumAssetsV2(
    options: SyncQueryOptions,
    response: Writable,
    checkpointMap: CheckpointMap,
    sessionId: string,
  ) {
    const backfillType = SyncEntityType.AlbumAssetBackfillV2;
    const backfillCheckpoint = checkpointMap[backfillType];
    const albums = await this.syncRepository.album.getCreatedAfter({
      ...options,
      afterCreateId: backfillCheckpoint?.updateId,
    });
    const updateType = SyncEntityType.AlbumAssetUpdateV2;
    const createType = SyncEntityType.AlbumAssetCreateV2;

View on GitHub (pinned to 199723261c)

Solutions

Replace SyncRequestType.AlbumAssetsV1 with SyncRequestType.AlbumAssetsV2 in the requested types.
Upgrade the client release and regenerate SDK from current openapi.
Clear cached sync preferences that pin the V1 type.

Example fix

// before
types: [SyncRequestType.AlbumAssetsV1]
// after
types: [SyncRequestType.AlbumAssetsV2]

Defensive patterns

Strategy: validation

Validate before calling

const types = clientTypes.filter(t => t !== SyncRequestType.AlbumAssetsV1);
types.push(SyncRequestType.AlbumAssetsV2);
await syncApi.stream({ types });

Type guard

function requestsAlbumAssetsV1(types: SyncRequestType[]): boolean {
  return types.includes(SyncRequestType.AlbumAssetsV1);
}

Prevention

Strip AlbumAssetsV1 from request arrays before sending.
Keep SDK and server version aligned.
Track the V2 backfill checkpoint (AlbumAssetBackfillV2) when migrating.

When it happens

Trigger: GET /sync/stream whose SyncRequestType array includes SyncRequestType.AlbumAssetsV1.

Common situations: Stale client still emitting AlbumAssetsV1 after server upgrade; SDK not regenerated.

Related errors

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/004b29393dd69bf5. Report an issue: GitHub.