Alias Paths Differ Only by Case
Q-5-25 — Alias Paths Differ Only by Case
Two paths differ only in capitalization, which macOS and Windows treat as the same file.
What this means
Linux filesystems are usually case-sensitive: Deploy.html and
deploy.html are two files. macOS and Windows, by default, are
not — there, they are one file, and whichever is written second
replaces the first.
This error fires when two aliases: entries resolve to paths that
differ only in case, or when one does so against a page the
project renders:
# one.qmd
aliases:
- /Deploy.html
# two.qmd
aliases:
- /deploy.html # the same file on macOS and WindowsWhy it is checked everywhere
The check runs on every platform, including case-sensitive ones. That is deliberate.
A site built on Linux CI where both files were written looks correct in the build log. Serve it from a case-insensitive filesystem — or let a contributor check it out on a Mac — and one redirect silently disappears. Catching it at build time on every platform is what makes the output portable.
The default assumes the stricter host. If yours is not — see below — you can say so.
How to fix it
Rename one of the two so they differ by more than capitalization. If both spellings need to work, pick one as the real alias; a case-insensitive host will serve it for either spelling anyway.
When the two really are different URLs
Some hosts keep paths that differ only by case apart: Amazon S3,
most Linux web servers, and anything else that treats a URL path as
an opaque string. A site served from one of these may have renamed
a directory from R/ to r/ and need the old /R/ URLs to keep
redirecting — which is exactly the pair this error rejects.
Declare the host case-sensitive in _quarto.yml:
website:
case-sensitive-paths: trueWith this set, a pair that differs only by case is two files, not a
collision, and the redirect is written. The check does not go away
entirely: when the directory being rendered into is itself
case-insensitive (a default macOS or Windows volume), writing the
redirect would replace the page it points at, so Quarto skips it
and warns Q-5-51 instead. Render on a case-sensitive
filesystem — typically the CI job that publishes the site — to get
both files.
Difference from Quarto 1
Quarto 1 compares paths as exact strings, so it never notices, and what it produces depends on where it runs. On Linux it writes both files, which is why sites deployed from Linux CI to a case-sensitive host have worked. On macOS or Windows the redirect lands on the page and replaces it with a redirect to itself.
Quarto 2 makes the outcome independent of the build machine: by
default the pair is rejected everywhere, and with
website.case-sensitive-paths: true the redirect is written where
the filesystem allows and reported where it does not.