---
title: "Azure Blob metadata with non-ASCII values fails in .NET and is retried as if transient"
url: "https://www.dariuszparys.com/notes/azure-blob-metadata-non-ascii-values"
author: "Dariusz Parys"
published: 2026-11-10T00:00:00.000Z
description: "Blob metadata travels as HTTP headers, so a file name with an umlaut makes the upload fail in .NET before it reaches Storage, and the Azure SDK retries it six times as if the error were transient."
---

# Azure Blob metadata with non-ASCII values fails in .NET and is retried as if transient

## 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's `HttpClient` throw before the request reaches Storage:

  ```
  HttpRequestException: Request headers must contain only ASCII characters.
  ```

- The Azure SDK's default retry policy treats that client-side `HttpRequestException` as retryable: 6 attempts, ~27 s, then an `AggregateException` _"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:

```kusto
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, outerMessage
```

The 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.EscapeDataString` or 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`.

```csharp
// 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),
    },
};
```
