dotnet/orleans · error · ArgumentOutOfRangeException

Data too large to write to Azure table. Size={0} MaxSize={1}

Error message

Data too large to write to Azure table. Size={0} MaxSize={1}

What it means

Thrown by CheckMaxDataSize when the serialized grain state exceeds the maximum allowed size for an Azure Table entity. Azure Table entities have a 1 MB total limit; Orleans splits data into chunks of MAX_STRING_PROPERTY_LENGTH (32 KB) with MAX_DATA_CHUNKS_COUNT (15), giving approximately 480 KB for string data plus binary data. When dataSize exceeds maxDataSize, an ArgumentOutOfRangeException is thrown.

Source

Thrown at src/Azure/Orleans.Persistence.AzureStorage/Providers/Storage/AzureTableStorage.cs:218

            else
            {
                var properties = SplitBinaryData(binaryData);

                foreach (var keyValuePair in properties.Zip(GetPropertyNames(BINARY_DATA_PROPERTY_NAME),
                (property, name) => new KeyValuePair<string, object>(name, property.ToArray())))
                {
                    entity[keyValuePair.Key] = keyValuePair.Value;
                }
            }
        }

        private void CheckMaxDataSize(int dataSize, int maxDataSize)
        {
            if (dataSize > maxDataSize)
            {
                var msg = string.Format("Data too large to write to Azure table. Size={0} MaxSize={1}", dataSize, maxDataSize);
                LogErrorDataTooLarge(dataSize, maxDataSize);
                throw new ArgumentOutOfRangeException("GrainState.Size", msg);
            }
        }

        private static IEnumerable<ReadOnlyMemory<char>> SplitStringData(ReadOnlyMemory<char> stringData)
        {
            var startIndex = 0;
            while (startIndex < stringData.Length)
            {
                var chunkSize = Math.Min(MAX_STRING_PROPERTY_LENGTH, stringData.Length - startIndex);

                yield return stringData.Slice(startIndex, chunkSize);

                startIndex += chunkSize;
            }
        }

        private static IEnumerable<ReadOnlyMemory<byte>> SplitBinaryData(ReadOnlyMemory<byte> binaryData)
        {

View on GitHub (pinned to fca799fa70)

Solutions

Move large state to Azure Blob Storage (use AddAzureBlobGrainStorage instead of AddAzureTableGrainStorage).
Split the grain into smaller grains with partitioned state.
Evict or compress data in grain state before it grows too large.
Store large binary payloads externally (Blob Storage) and keep only a reference/URI in grain state.

Example fix

// before: large grain state in table storage
[StorageProvider(ProviderName = "tableStore")]
public class BigGrain : Grain, IBigGrain
{
    private List<byte[]> _largeData; // exceeds table limits
}

// after: use blob storage for large state
[StorageProvider(ProviderName = "blobStore")]
public class BigGrain : Grain, IBigGrain { }

Defensive patterns

Strategy: validation

Validate before calling

// Before writing, check serialized state size
var serialized = storageSerializer.Serialize(grainState.State);
if (serialized.Length > 480 * 1024) // approx table limit
    throw new InvalidOperationException($"Grain state too large ({serialized.Length} bytes) for Azure Table Storage. Use Blob Storage.");

Try / catch

try { await grain.WriteStateAsync(); }
catch (ArgumentOutOfRangeException ex) when (ex.Message.Contains("Data too large"))
{
    logger.LogError(ex, "Grain state exceeds Azure Table size limit — move to Blob Storage.");
    throw;
}

Prevention

Monitor grain state size and enforce an application-level limit before it hits the storage limit.
Design grain state to be compact — store references to large blobs instead of inline data.
Use Azure Blob Storage for grains with large state.
Implement eviction/compression for growing collections in grain state.

When it happens

Trigger: A grain state object serializes to a payload larger than the configured maxDataSize (derived from chunk size * chunk count). This is checked in ConvertToStorageFormat before attempting the write to Azure Table.

Common situations: Grain state contains large collections, embedded files, images, or deeply nested objects. Accumulating unbounded data in grain state (e.g., a shopping cart or log buffer that grows without eviction). Changing a grain's state schema to include large fields. Using Azure Table Storage for data that belongs in Blob Storage.

Related errors

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