dotnet/orleans · error · OrleansConfigurationException

Configuration for DynamoDBGrainStorage {name} is invalid. Ta

Error message

Configuration for DynamoDBGrainStorage {name} is invalid. TableName is not valid.

What it means

Thrown by DynamoDBGrainStorageOptionsValidator.ValidateConfiguration during silo startup when the TableName on DynamoDBStorageOptions is null, empty, or whitespace. Orleans runs configuration validators before the silo accepts clients, so this fails the host fast rather than at the first grain write.

Source

Thrown at src/AWS/Orleans.Persistence.DynamoDB/Options/DynamoDBStorageOptions.cs:87

    {
        private readonly DynamoDBStorageOptions 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 DynamoDBGrainStorageOptionsValidator(DynamoDBStorageOptions options, string name)
        {
            this.options = options;
            this.name = name;
        }

        public void ValidateConfiguration()
        {
            if (string.IsNullOrWhiteSpace(this.options.TableName))
                throw new OrleansConfigurationException(
                    $"Configuration for DynamoDBGrainStorage {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 DynamoDBGrainStorage {this.name} is invalid. {nameof(this.options.ReadCapacityUnits)} is not valid.");

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

View on GitHub (pinned to fca799fa70)

Solutions

Set options.TableName to a non-empty DynamoDB table name when configuring the storage provider.
If the name comes from configuration, verify that config key exists and is non-empty (log it during startup without leaking credentials).
Create the table in DynamoDB beforehand if auto-create is off.

Example fix

// before
silo.AddDynamoDBGrainStorage("storage", o => { /* TableName omitted */ });

// after
silo.AddDynamoDBGrainStorage("storage", o => { o.TableName = "OrleansGrainState"; o.Service = ...; });

Defensive patterns

Strategy: validation

Validate before calling

// Assert the table name is set before starting the silo
if (string.IsNullOrWhiteSpace(options.TableName))
    throw new InvalidOperationException("Set DynamoDBStorageOptions.TableName before silo start.");

Type guard

static bool HasTableName(DynamoDBStorageOptions o) => !string.IsNullOrWhiteSpace(o.TableName);

Try / catch

null

Prevention

Always set TableName in the options lambda.
Pull the table name from a known config key and assert it is non-empty at startup.
Pre-create the DynamoDB table if auto-create is disabled.

When it happens

Trigger: Registering DynamoDB grain storage (e.g. AddDynamoDBGrainStorage / UseDynamoDBGrainStorage) without setting options.TableName, or setting it to an empty string.

Common situations: Reading TableName from a missing config key/environment variable; a typo in the options lambda; copying a storage registration block and forgetting to rename the table.

Related errors

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