What are Blob Name normalization rules in Azure Blob operations

John Doe 0 Reputation points
2026-10-02T13:57:06.46+00:00

Recently, I encountered an undocumented Put Blob API behavior when creating blob names containing . and .. path segments - it feels like they had filesystem-like semantics and the final path would not contain them. Although the documentation tells that it's not recommended to use certain characters and combinations of them, the normalization process is nowhere to learn about. Specifically, is there maybe a piece of documentation or there's a log under my nose that I'm refusing to notice, which explains these fine details?

Azure Blob Storage
Azure Blob Storage

An Azure service that stores unstructured data in the cloud as blobs.

0 comments

1 answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. HassanNazeer 0 Reputation points
    2026-10-19T04:14:58.0666667+00:00

    There isn't a separate "normalization algorithm" page beyond the Blob naming rules, but the behaviour you're seeing lines up with how names are carried in the request URL.

    Documented rules (Put Blob and friends):

    • A blob name may contain most characters, 1–1024 chars, case-sensitive.
    • Names are path-like when you use / as a delimiter for virtual directories.
    • No path segment should end with a dot (.); avoid names that end with ., /, \, or combinations of those.
    • Reserved URL characters must be percent-encoded (client libraries usually do this for you).
    • Path-segment count limits: 254 segments without hierarchical namespace; 63 with HNS (including account/container segments).

    So folder/../file.txt or segments that are . / .. are not a supported "go up a directory" feature of Blob Storage. The service is not a real filesystem. Clients, gateways, or URL parsers often resolve . and .. before the name is stored, which is why the final blob name can look "collapsed". If you need those characters literally in a segment, don't put unescaped . / .. path segments in the URL; redesign the name (for example use a different delimiter or encode the segment) so the request URI never contains a traversable path form.

    Practical guidance:

    1. Treat the blob name as an opaque string that happens to allow / for listing prefixes — not as NTFS/POSIX paths.
    2. Never end a segment with ..
    3. If you must preserve odd characters, percent-encode and verify with a raw REST Put using a tool that does not normalize the path (or use the SDK overload that takes the blob name as a string without going through a file-path API).
    4. For hierarchical namespace accounts, directory names follow the same "don't end with ." note.

    Was this answer helpful?

    0 comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.