dotnet/orleans · error · ArgumentException

Invalid blob name

Error message

Invalid blob name

What it means

Thrown by AzureBlobUtils.ValidateBlobName when a blob name fails Azure Blob Storage naming rules: null/whitespace, longer than 1024 characters, or containing 254 or more forward-slash characters. Orleans uses blob names to address grain state and stream data, so an invalid name makes the blob address impossible to resolve. This is a hard pre-flight check that runs before any Azure call.

Source

Thrown at src/Azure/Shared/Storage/AzureBlobUtils.cs:33

    /// </summary>
    internal static partial class AzureBlobUtils
    {
        [GeneratedRegex("^[a-z0-9]+(-[a-z0-9]+)*$", RegexOptions.ExplicitCapture | RegexOptions.Singleline | RegexOptions.CultureInvariant)]
        private static partial Regex ContainerNameRegex();

        internal static void ValidateContainerName(string containerName)
        {
            if (string.IsNullOrWhiteSpace(containerName) || containerName.Length < 3 || containerName.Length > 63 || !ContainerNameRegex().IsMatch(containerName))
            {
                throw new ArgumentException("Invalid container name", nameof(containerName));
            }
        }

        internal static void ValidateBlobName(string blobName)
        {
            if (string.IsNullOrWhiteSpace(blobName) || blobName.Length > 1024 || blobName.Count(c => c == '/') >= 254)
            {
                throw new ArgumentException("Invalid blob name", nameof(blobName));
            }
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

1. Ensure the blob name is non-null, non-blank, at most 1024 chars, and has fewer than 254 '/' characters before invoking storage.
2. If the name comes from a grain key, hash or truncate composite keys and avoid stacking '/' separators.
3. Wrap name construction in a helper that calls AzureBlobUtils.ValidateBlobName (or mirrors its rules) so invalid names fail fast in your code, not inside Orleans.

Example fix

// before
var blobName = grainKey.ToString();   // grainKey may be null/very long
// after
var raw = grainKey?.ToString() ?? throw new ArgumentNullException(nameof(grainKey));
var blobName = raw.Length > 1024 ? Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(raw))) : raw;
if (blobName.Count(c => c == '/') >= 254) throw new ArgumentException("Blob name has too many path segments");

static void EnsureValidBlobName(string name)
{
    if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("blob name required");
    if (name.Length > 1024) throw new ArgumentException("blob name too long");
    if (name.Count(c => c == '/') >= 254) throw new ArgumentException("too many path segments");
}

static bool IsValidBlobName(string? name) =>
    !string.IsNullOrWhiteSpace(name) && name.Length <= 1024 && name.Count(c => c == '/') < 254;

catch (ArgumentException ex) when (ex.Message == "Invalid blob name") { /* log the offending key source and fail the grain operation */ }

When it happens

Trigger: Calling a code path that constructs a blob name from a null grain key, an unbounded user string, a very long composite key, or a key that embeds many '/' separators. Common with Azure Blob persistence (AzureBlobGrainStorage) and blob-based streaming providers when GrainReference.ToParcelableString or a custom key builder yields an out-of-range value.

Common situations: Passing an unchecked user-supplied primary key as the blob name; concatenating many key parts with '/' delimiters; upgrading grain key schemes that suddenly produce long names; null key after a deserialization bug.

Related errors

• Value cannot be null. (Parameter 'createClientCallback')
• Value cannot be null. (Parameter 'connectionString')
• Value cannot be null. (Parameter 'serviceUri')
• Value cannot be null. (Parameter 'tokenCredential')
• Value cannot be null. (Parameter 'azureSasCredential')

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