Context
ASP.NET Core API storing user uploads in Azure Blob Storage with Azure.Storage.Blobs. The upload wrote the user’s original file name into blob metadata (BlobUploadOptions.Metadata). An upload with an umlaut in its name returned a generic 500 after about 27 seconds; other uploads worked. Users reported “sometimes the upload fails, regardless of size”.
Insight
-
Blob metadata (
x-ms-meta-*) travels as HTTP request headers, so values must be ASCII. A non-ASCII value (ä,ö,ü,ß, …) makes .NET’sHttpClientthrow before the request reaches Storage:HttpRequestException: Request headers must contain only ASCII characters. -
The Azure SDK’s default retry policy treats that client-side
HttpRequestExceptionas retryable: 6 attempts, ~27 s, then anAggregateException“Retry failed after 6 tries”. The real cause is only in the inner exceptions. -
File size is irrelevant. Only the characters in the name decide whether the upload fails.
Finding it
Join failed requests to their exceptions on operation_Id in Application Insights:
requests| where name startswith "POST /api/..." and toint(resultCode) >= 500| join kind=leftouter (exceptions | project operation_Id, type, outerMessage) on operation_Id| project timestamp, resultCode, type, outerMessageThe outer exception only says the retries failed. Expand the inner exceptions of the AppExceptions rows for the failing operation to see the ASCII error.
Fix
- Keep display names in your database, not in blob metadata. Often nothing reads that metadata back, and then the entry can be dropped.
- If you need the name on the blob, encode it on write (
Uri.EscapeDataStringor Base64) and decode it on read. - Check every store that writes user-supplied strings into metadata, not just the one that failed.
- Add a contract test (e.g. against Azurite) that uploads a file named
Prüfung ß.pdf.
// Breaks on "Prüfung ß.pdf":// Metadata = new Dictionary<string, string> { ["originalFileName"] = fileName }
BlobUploadOptions options = new(){ HttpHeaders = new BlobHttpHeaders { ContentType = contentType }, // Only ASCII values here; encode if a user string must go in: Metadata = new Dictionary<string, string> { ["originalFileName"] = Uri.EscapeDataString(fileName), },};