dotnet/orleans · error · OrleansConfigurationException

Configuration for DynamoDBTransactionalStateStorage {this.na

Error message

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

What it means

Thrown by DynamoDBTransactionalStorageOptionsValidator.ValidateConfiguration when UseProvisionedThroughput is true but ReadCapacityUnits is 0. Provisioned throughput mode requires explicit capacity units; a zero value is invalid for DynamoDB, so the validator rejects the configuration at startup before any operation.

Source

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

    /// <param name="options">The option to be validated.</param>
    /// <param name="name">The option name to be validated.</param>
    public DynamoDBTransactionalStorageOptionsValidator(DynamoDBTransactionalStorageOptions options, string name)
    {
        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 ReadCapacityUnits to a positive value when UseProvisionedThroughput is true.
If you want on-demand billing, leave UseProvisionedThroughput = false instead.
Right-size the value from observed read load and DynamoDB consumption metrics.
Add a config sanity check in your deployment pipeline for provisioned capacity > 0.

Example fix

// before
opt.UseProvisionedThroughput = true; // ReadCapacityUnits 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.ReadCapacityUnits <= 0)
    throw new OrleansConfigurationException("ReadCapacityUnits must be > 0 when provisioned.");

Try / catch

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

Prevention

Set ReadCapacityUnits when enabling provisioned throughput.
Prefer on-demand mode unless capacity is planned.
Add a pipeline check for provisioned capacity > 0.

When it happens

Trigger: Enabling UseProvisionedThroughput while leaving ReadCapacityUnits at its default 0, or setting it explicitly to 0. The validator runs during configuration validation at silo startup.

Common situations: Copying a template that sets UseProvisionedThroughput=true but omits capacity units; toggling to provisioned mode from on-demand without filling in capacity; misreading the option as optional.

Related errors

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