DynamoDB TransactionCanceledException

TL;DR — TransactWriteItems / TransactGetItems'ınızdaki bir (ya da daha fazla) öğe başarısız oldu, dolayısıyla DynamoDB tüm işlemi geri aldı. Gerçek neden CancellationReasons dizisindedir — onu okuyun; öğe başına neden Code'u size tam olarak hangi öğe ve neden olduğunu söyler.

Ne anlama gelir

DynamoDB işlemleri ya hep ya hiçtir. Herhangi bir öğenin koşulu başarısız olursa, kapasite aşılırsa ya da iki işlem çakışırsa, her şey iptal edilir ve hiçbir şey yazılmaz. Üst düzey mesaj geneldir:

TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None, TransactionConflict]

Köşeli parantez içindeki liste konumsaldır — işleminizdeki her öğe için bir girdi, sırayla. DynamoDB bu istisnayı HTTP durum kodu 400 ile döndürür ve AWS SDK'ları onu otomatik olarak yeniden denemez — kodunuz, neden koduna göre bir yeniden denemenin mantıklı olup olmadığına karar verir.

Neden olur (neden kodları)

• ConditionalCheckFailed — o öğenin ConditionExpression'ı false olarak değerlendirildi (ConditionalCheckFailedException'a bakın).
• TransactionConflict — başka bir eşzamanlı işlem (ya da yazma) aynı öğe üzerinde çalışıyor; geri çekilmeyle yeniden deneyin.
• ProvisionedThroughputExceeded — öğenin tablosunun/indeksinin kapasitesi tükendi.
• ThrottlingError — tablo ya da indeks (genellikle talep üzerine, DynamoDB onu hâlâ ölçeklendirirken) yazmayı kısıtladı; geri çekilmeyle yeniden deneyin.
• ValidationError — o öğe hatalı biçimlendirilmişti (geçersiz parametre değerleri, belge yolu, işlenen türü, boyut taşması, …).
• ItemCollectionSizeLimitExceeded — bir LSI öğe koleksiyonu 10 GB'ye çarptı.
• None — o öğe sorunsuzdu; hata listede başka yerdeydi.

Bu, belgelenmiş kod kümesinin tamamıdır. Bir yinelenen öğe anahtarının (iki eylem tarafından hedeflenen aynı öğe) bir iptal kodu olmadığını unutmayın — DynamoDB o isteği bunun yerine en baştan bir ValidationException olarak reddeder.

Nasıl düzeltilir

1. Yalnızca mesajı değil, hatadaki CancellationReasons'ı okuyun. Her girdiyi indekse göre girdi öğenize geri eşleyin.
2. Koda göre dallanın: ConditionalCheckFailed → iş mantığı; TransactionConflict/ThrottlingError/ProvisionedThroughputExceeded → üstel geri çekilmeyle yeniden deneyin; ValidationError → isteği düzeltin.
3. Yinelenen anahtarlardan kaçının — tek bir işlem aynı öğeye iki kez dokunamaz.

Öğeleri elle mi düzenliyorsunuz? DynoTable'ın hazırlama alanı, düzenlemelerinizi tek bir işlemsel yazmada toplar ve göndermeden önce her öğeyi gözden geçirmenize izin verir — isteği elle kurmadan aynı ya-hep-ya-hiç semantiği.

Örnek

import {DynamoDBClient, TransactionCanceledException} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, TransactWriteCommand} from '@aws-sdk/lib-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

try {
  await doc.send(new TransactWriteCommand({TransactItems: [/* ... */]}));
} catch (err) {
  if (err instanceof TransactionCanceledException) {
    for (const [i, reason] of (err.CancellationReasons ?? []).entries()) {
      if (reason.Code && reason.Code !== 'None') {
        console.error(`item ${i} cancelled: ${reason.Code} — ${reason.Message}`);
      }
    }
  }
  throw err;
}

SSS

DynamoDB işlemim neden iptal edildi? TransactWriteItems/TransactGetItems'taki bir öğe başarısız oldu — bir koşul kontrolü, bir verim/kısıtlama sınırı ya da başka bir eşzamanlı işlemle bir çakışma — dolayısıyla DynamoDB tüm işlemi geri aldı ve hiçbir şey yazmadı. Öğe başına neden CancellationReasons dizisindedir.

İşlemdeki hangi öğenin başarısız olduğunu nasıl bulurum? TransactionCanceledException üzerindeki CancellationReasons dizisini okuyun. Girdi öğesi başına bir girdisi vardır, aynı sırada; Code'u "None" olmayan girdi, iptale neden olan öğedir.

Nasıl yeniden oluşturulur

Tek bir işlemde iki yazma; ikincisi, sağlanması mümkün olmayan bir koşulla korunuyor. İşlemin tamamı geri alınır ve eylem başına kararlar CancellationReasons içinde gelir — TransactItems ile konum olarak hizalanmış hâlde:

await client.send(
  new TransactWriteItemsCommand({
    TransactItems: [
      {Put: {TableName: 'orders', Item: {pk: {S: 'OK'}, sk: {S: 'META'}}}},
      {
        Put: {
          TableName: 'orders',
          Item: {pk: {S: 'ORDER#1'}, sk: {S: 'META'}},
          ConditionExpression: 'attribute_not_exists(pk)' // ORDER#1 already exists
        }
      }
    ]
  })
);

Gerçek çıktı:

TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [None, ConditionalCheckFailed]
HTTP 400

error.CancellationReasons:
[
  {
    "Code": "None"
  },
  {
    "Code": "ConditionalCheckFailed",
    "Message": "The conditional request failed"
  }
]

İlk eylem None bildirir — başarısız olmadı, komşusu olduğu için geri alındı. Yalnızca Code'u None olmayan girdi asıl suçluyu tanımlar ve onun indeksi, kendi TransactItems dizinizdeki sorunlu eylemin indeksidir.

İlgili hatalar

• ConditionalCheckFailedException
• ProvisionedThroughputExceededException
• Kod örneği: TransactWriteItems in Node.js · Python (boto3) ile — karşılaştırılacak çalıştırılabilir bir işlem.
• Öğrenin: DynamoDB transactions

Kaynaklar

• TransactWriteItems — Amazon DynamoDB API Reference
• TransactGetItems — Amazon DynamoDB API Reference
• Amazon DynamoDB Transactions: How it works — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.

2026-07-26 tarihinde AWS SDK for JavaScript v3.1095.0 ile DynamoDB Local 2.x'e karşı yeniden üretildi — yukarıdaki çıktı birebir alınmıştır.