dotnet/orleans · error · ArgumentException

Azure Table partition keys must not exceed 1,024 characters.

Error message

Azure Table partition keys must not exceed 1,024 characters.

What it means

Thrown by ValidatePartitionKey when a computed partition key exceeds 1,024 characters. Azure Tables caps partition keys at 1 KiB; this check prevents a request that the service would reject, and applies to both the default percent-encoding mapper and custom mappers.

Source

Thrown at src/Azure/Orleans.Journaling.AzureStorage/AzureTableJournalStorageOptions.cs:154

                nameof(TableName));
        }

        foreach (var character in tableName)
        {
            if (!IsAsciiLetter(character) && character is not (>= '0' and <= '9'))
            {
                throw new ArgumentException(
                    "Azure Table names must contain 3 to 63 alphanumeric characters and begin with a letter.",
                    nameof(TableName));
            }
        }
    }

    private static void ValidatePartitionKey(string partitionKey, string parameterName)
    {
        if (partitionKey.Length > 1024)
        {
            throw new ArgumentException(
                "Azure Table partition keys must not exceed 1,024 characters.",
                parameterName);
        }

        foreach (var character in partitionKey)
        {
            if (character is '/' or '\\' or '#' or '?'
                or >= '\u0000' and <= '\u001F'
                or >= '\u007F' and <= '\u009F')
            {
                throw new ArgumentException(
                    "Azure Table partition keys must not contain '/', '\\', '#', '?', or control characters.",
                    parameterName);
            }
        }
    }

    private static bool IsAsciiLetter(char character)

View on GitHub (pinned to fca799fa70)

Solutions

Shorten the JournalId.Value source so the encoded key stays under 1,024 chars.
Provide a custom GetPartitionKey mapper that hashes or truncates the id deterministically (e.g. a stable hash) while remaining unique enough.
Avoid embedding full type names/URIs into the JournalId value.

Example fix

// before
var journalId = new JournalId(grainType.FullName + ":" + key); // may encode >1024
// after
var journalId = new JournalId(Sha1Hash(grainType.FullName + ":" + key));

Defensive patterns

Strategy: validation

Validate before calling

var encoded = Uri.EscapeDataString(journalId.Value);
if (encoded.Length > 1024)
    throw new ArgumentException("Encoded partition key exceeds 1024 chars; shorten or hash the id.");

Type guard

static bool FitsPartitionKeyLimit(JournalId id) => Uri.EscapeDataString(id.Value).Length <= 1024;

Prevention

Keep JournalId.Value sources short; avoid full type names or URLs.
If ids can be long, use a custom mapper with a stable hash.
Remember percent-encoding can triple the length of special chars.

When it happens

Trigger: A JournalId.Value is long enough that Uri.EscapeDataString (or a custom GetPartitionKey mapper) produces a string longer than 1,024 chars; ValidatePartitionKey is then called from GetPartitionKeyForJournal or GetDefaultPartitionKey.

Common situations: Using a very long grain-type name or a composite key as the JournalId value; a custom mapper that concatenates multiple fields without truncation; percent-encoding triples the length of certain characters, inflating an already-long id.

Related errors

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