dotnet/orleans · error · OrleansConfigurationException

Configuration for DynamoDBTransactionalStateStorage {this.na

Error message

Configuration for DynamoDBTransactionalStateStorage {this.name} is invalid. WriteCapacityUnits is not valid.

What it means

Thrown by DynamoDBTransactionalStorageOptionsValidator.ValidateConfiguration when UseProvisionedThroughput is true but WriteCapacityUnits is 0. Same rationale as the read-units check: provisioned DynamoDB tables require a positive write capacity, and the validator enforces it at startup.

Source

Thrown at src/AWS/Orleans.Transactions.DynamoDB/Options/DynamoDBTransactionalStorageOptions.cs:108

        this.options = options;
        this.name = name;
    }

    /// <inheritdoc />
    public void ValidateConfiguration()
    {
        if (string.IsNullOrWhiteSpace(this.options.TableName))
            throw new OrleansConfigurationException(
                $"Configuration for DynamoDBTransactionalStateStorage {this.name} is invalid. {nameof(this.options.TableName)} is not valid.");

        if (this.options.UseProvisionedThroughput)
        {
            if (this.options.ReadCapacityUnits == 0)
                throw new OrleansConfigurationException(
                    $"Configuration for DynamoDBTransactionalStateStorage {this.name} is invalid. {nameof(this.options.ReadCapacityUnits)} is not valid.");

            if (this.options.WriteCapacityUnits == 0)
                throw new OrleansConfigurationException(
                    $"Configuration for DynamoDBTransactionalStateStorage {this.name} is invalid. {nameof(this.options.WriteCapacityUnits)} is not valid.");
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Set WriteCapacityUnits to a positive value whenever UseProvisionedThroughput is true.
Use on-demand mode (UseProvisionedThroughput = false) if capacity planning is unwanted.
Base the value on transaction commit write load and DynamoDB throttling metrics.
Add a startup assertion that both capacity units are > 0 when provisioned.

Example fix

// before
opt.UseProvisionedThroughput = true; // WriteCapacityUnits default 0 -> validator throws

// after
opt.UseProvisionedThroughput = true;
opt.ReadCapacityUnits = 50;
opt.WriteCapacityUnits = 25;

Defensive patterns

Strategy: validation

Validate before calling

if (options.UseProvisionedThroughput && options.WriteCapacityUnits <= 0)
    throw new OrleansConfigurationException("WriteCapacityUnits must be > 0 when provisioned.");

Try / catch

try { /* build silo */ }
catch (OrleansConfigurationException ex) when (ex.Message.Contains("WriteCapacityUnits"))
{
    logger.LogCritical("Set DynamoDB WriteCapacityUnits > 0 or disable provisioned throughput.");
    throw;
}

Prevention

Set WriteCapacityUnits when enabling provisioned throughput.
Base the value on observed commit write load.
Assert both capacity units are > 0 in your deployment checks.

When it happens

Trigger: Enabling UseProvisionedThroughput while leaving WriteCapacityUnits at default 0, or explicitly zeroing it. Validator runs at configuration validation during host/silo build.

Common situations: Template/config sets provisioned mode but omits write units; switching billing modes without updating capacity; assuming write units default to a sane non-zero value (they do not).

Related errors

AI-assisted analysis of dotnet/orleans@fca799fa70 (2026-08-13). Data as JSON: /api/errors/5edd478f10a30197. Report an issue: GitHub.