DynamoDB Streams: TrimmedDataAccessException

TL;DR — O DynamoDB Streams mantém registros por 24 horas; registros mais antigos são cortados e sumidos do stream. Esta exceção significa que você pediu uma posição que foi cortada — um checkpoint com mais de um dia, normalmente de um consumidor que estava fora do ar ou ficou para trás. Você não consegue recuperar esses registros do stream: retome de TRIM_HORIZON (registro sobrevivente mais antigo) e reconcilie a lacuna a partir da própria tabela.

O que significa

TrimmedDataAccessException: The data you are trying to access has been trimmed.

Ao contrário de um iterator expirado — onde apenas seu handle de posição ficou obsoleto — dados cortados são genuinamente removidos. Solicitar um shard iterator em um SequenceNumber cortado, ou ler um shard cujos registros expiraram, lança isto. O stream é um buffer deslizante de 24 horas, não um arquivo.

Por que acontece

O consumidor esteve fora do ar por mais de 24 horas — uma interrupção, um worker pausado, um trigger desabilitado esquecido — e seu checkpoint agora aponta para território cortado.
O atraso de processamento excedeu a retenção — o consumidor roda, mas mais devagar que a taxa de escrita, e desviou mais de um dia para trás.
Um checkpoint armazenado obsoleto — reiniciar um consumidor antigo com um SequenceNumber persistido semanas atrás.
Ler um shard antigo de ponta a ponta — percorrer a linhagem de shards de um stream de longa duração e solicitar intervalos que antecedem a retenção.

Como corrigir

Retome do registro disponível mais antigo e aceite a lacuna:

const {ShardIterator} = await streams.send(
  new GetShardIteratorCommand({
    StreamArn: streamArn,
    ShardId: shardId,
    ShardIteratorType: 'TRIM_HORIZON' // oldest untrimmed record
  })
);

Use LATEST em vez disso se apenas a nova atividade importa.

Reconcilie a janela perdida a partir da fonte da verdade — a tabela ainda tem o estado atual de todo item. Um Scan/Query limitado sobre as chaves afetadas (ou uma exportação para tabelas grandes) reconstrói o que os registros cortados teriam te dito, menos as versões intermediárias.
Alerte sobre o atraso do consumidor — monitore a idade dos registros que você está processando (ou a métrica IteratorAge do Lambda) e acione muito antes de se aproximar de 24 horas.
Precisa de retenção mais longa? Faça stream para um buffer durável conforme os registros chegam (por exemplo, Kinesis Data Streams via padrões de Kinesis adapter, ou persista os registros processados você mesmo) — o próprio DynamoDB Streams não pode ser estendido além de 24 horas.

Reconstruir o estado após uma lacuna significa olhar o que de fato está na tabela agora — o app desktop DynoTable torna essa passagem de reconciliação uma consulta navegável em vez de um script. Dimensionando a leitura de recuperação? A calculadora de preços do DynamoDB estima o custo de RCU.

Erros relacionados

ExpiredIteratorException — o primo recuperável: posição obsoleta, dados ainda lá.
Stream not enabled
Invalid StreamArn
Aprenda: DynamoDB Streams

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.