dotnet/orleans · error · OrleansConfigurationException

Configuration for DynamoDBTransactionalStateStorage {this.na

Error message

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

What it means

Thrown by DynamoDBTransactionalStorageOptionsValidator.ValidateConfiguration when TableName is null/whitespace. DynamoDB transactional state requires a concrete table to store grain transaction metadata; an empty name means the options were not configured, and Orleans surfaces this as OrleansConfigurationException during validation (typically at silo startup).

Source

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

    private readonly DynamoDBTransactionalStorageOptions options;
    private readonly string name;

    /// <summary>
    /// Constructor
    /// </summary>
    /// <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

1. Set TableName in DynamoDBTransactionalStorageOptions: configure options.UseDynamoDBTransactionalStateStorage(o => o.TableName = "...").
2. Confirm the config section name and key ('TableName') match exactly and are bound to the options.
3. Load environment-specific configuration (appsettings.{Env}.json, env vars) before validation.
4. Ensure the table exists in DynamoDB (or auto-create is enabled) once the name is set.

Example fix

// before
builder.AddDynamoDBTransactionalStateStorage("tx", opt => { }); // no TableName -> validator throws

// after
builder.AddDynamoDBTransactionalStateStorage("tx", opt =>
{
    opt.TableName = "OrleansTransactionState";
    opt.Service = "us-west-2";
});

if (string.IsNullOrWhiteSpace(options.TableName))
    throw new OrleansConfigurationException("DynamoDBTransactionalStorage TableName is required.");

static bool IsValidTableName(string? s) => !string.IsNullOrWhiteSpace(s);

try { /* build silo */ }
catch (OrleansConfigurationException ex) when (ex.Message.Contains("TableName"))
{
    logger.LogCritical("DynamoDB transactional storage TableName missing in config.");
    throw;
}

When it happens

Trigger: Calling AddDynamoDBTransactionalStateStorage without configuring TableName, or binding options from a config section where TableName is absent/blank. The validator runs during host build / silo lifecycle validation.

Common situations: Missing 'TableName' in the DynamoDBTransactionalStorage config section; typo in the key name; environment config not loaded; copy-paste from a non-transactional DynamoDB storage config that omits the table.

Related errors

• Configuration for DynamoDBTransactionalStateStorage {this.na
• Configuration for DynamoDBTransactionalStateStorage {this.na
• The transactional state storage provider name is required.
• Storage state corrupted: no record for committed state v{thi
• Load must be called after a failed Store before this storage

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