`pnpm create astro` fails silently on Linux when path contains non-ASCII characters (Unicode NFC vs NFD normalization bug)

[kcabdussamed]

Astro Info

Astro v4.x (Latest via pnpm create astro@latest)
OS: Manjaro Linux (Kernel v6.x)
Package Manager: pnpm v11.13.0
Shell: zsh

If this issue only occurs in one browser, which browser is a problem?

Not a browser issue. It occurs during the CLI scaffolding process in the terminal.

Describe the Bug

When running pnpm create astro@latest inside a directory path that contains non-ASCII/Unicode characters (e.g., Turkish characters like ü in /home/saqut/Masaüstü/), the installation script finishes with a successful exit code ("Project initialized!"), but the target directory remains empty except for root monorepo files. The src/ folder, package.json, and astro.config.mjs are missing.

By tracing the system calls using strace, we uncovered that the scaffolding tool uses NFD (Decomposed Unicode) format for path names, while Linux (ext4) expects NFC (Canonical Decomposition).

As seen in the strace log below, Node/Astro tries to resolve the path using NFD components (Masau\314\210stu\314\210 instead of Masaüstü):

86653 openat(AT_FDCWD, "/home/saqut/Masau\314\210stu\314\210/saqutcompiler/webside/deneme/astro.config.mjs", O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW|O_CLOEXEC, 0664) = 31
86656 openat(AT_FDCWD, "/home/saqut/Masau\314\210stu\314\210/saqutcompiler/webside/deneme/package.json", O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW|O_CLOEXEC, 0664) = 32

### What's the expected result?

The installer should sanitize, normalize, or preserve the exact Unicode normalization form (NFC) used by the host OS filesystem, ensuring that files like package.json and the src/ directory are successfully written to the correct physical path.

### Link to Minimal Reproducible Example

https://github.com/withastro/astro#NFC-NFD-Unicode-Path-Bug

### Participation

- [ ] I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Yes
• Exploration: Yes — View branch
• Unit Test: Yes — packages/create-astro/test/units/relocate-nfd.test.ts
• Priority: P4: important. This silently produces a broken project (missing package.json, src/, astro.config.mjs) for any Linux user whose directory path contains characters with NFC/NFD variants (Turkish, German, French, Scandinavian, etc.), and the CLI reports success with exit code 0, making it very difficult to diagnose.

The root cause is in modern-tar (v0.3.5, a transitive dependency via @bluwy/giget-core), which unconditionally normalizes all paths containing non-ASCII characters to NFD (decomposed Unicode) form. On Linux ext4 (and most Linux filesystems), NFC and NFD are distinct byte sequences, so modern-tar creates a separate NFD-encoded directory and writes template files there, while create-astro's own post-processing code writes to the original NFC directory. The user ends up with only AGENTS.md/CLAUDE.md in their project — all template files (package.json, src/, astro.config.mjs) are silently written to an invisible sibling directory.

I found a potential fix for this issue. After downloadTemplate completes, the fix detects if an NFD-variant directory was created (by comparing inodes to distinguish real duplicates from macOS filesystem aliases), moves all extracted files back to the correct NFC directory, and cleans up the orphaned NFD directory hierarchy.

Try this fix

You can test this fix right now without waiting for a release:

pnpm add https://pkg.pr.new/create-astro@10879bb

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Reproduction

Created a directory with NFC-encoded Turkish characters (Masaüstü, where ü = \xc3\xbc) and ran create-astro inside it. Compared results with ASCII-only and CJK (no NFC/NFD decomposition) paths:

Path type	Template files present?
ASCII (/tmp/test_ascii/project/)	✅ Yes — all files
CJK (/tmp/日本語/project/)	✅ Yes — all files
Turkish NFC (/tmp/Masaüstü/project/)	❌ No — only AGENTS.md and CLAUDE.md

The find command revealed two separate directories under the test root:

• Masa\xc3\xbc st\xc3\xbc (NFC, original) — contained only AGENTS.md
• Masau\xcc\x88stu\xcc\x88 (NFD, created by modern-tar) — contained all template files

Root Cause

The dependency chain is: create-astro → @bluwy/giget-core → modern-tar (v0.3.5).

In modern-tar's dist/fs/index.js, the normalizeUnicode function:

const normalizeUnicode = (s) => {
    result = result ?? s.normalize("NFD");
    // ...
};

This is called on the destination directory path during extraction:

const resolvedDestDir = normalizeUnicode(path.resolve(directoryPath));
await fs.mkdir(resolvedDestDir, { recursive: true });

On macOS (HFS+/APFS), NFD normalization is harmless because the filesystem treats NFC and NFD identically. On Linux ext4 (byte-transparent), they are different paths, so mkdir creates a new directory.

Fix

Added relocateNFDFiles() in packages/create-astro/src/actions/template.ts, called immediately after downloadTemplate. The function:

1. Computes the NFD variant of the resolved cwd
2. Early-returns if the path is ASCII-only (no NFD difference) or if the NFD path doesn't exist
3. Compares inodes to confirm NFC and NFD are truly separate directories (handles macOS where they'd be the same)
4. Moves all entries from the NFD directory to the NFC directory via fs.renameSync
5. Cleans up empty NFD parent directories via fs.rmdirSync

Tests

Added 3 unit tests in packages/create-astro/test/units/relocate-nfd.test.ts:

• Moves files from NFD directory to NFC directory
• No-op for ASCII-only paths
• No-op when NFD directory does not exist

Tests are automatically skipped on macOS (where the filesystem normalizes NFC/NFD to the same inode). All 125 tests pass (122 existing + 3 new).

Upstream Note

The ideal long-term fix would be in modern-tar itself — the NFD normalization should be conditional on the platform/filesystem. This fix is a workaround in create-astro to unblock affected users.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[felmonon]

Confirmed the bot's root-cause diagnosis against the upstream source, independently of the exploration branch.

modern-tar's src/fs/path.ts unconditionally NFD-normalizes any string containing non-ASCII characters (s.normalize("NFD") in normalizeUnicode, LRU-cached), and applies it not just to tar header names (normalizeHeaderName) but to the resolved destination path in validateBounds (normalizeUnicode(path.resolve(targetPath))). So the extraction target /home/.../Masaüstü/... is itself rewritten from NFC to NFD before any writes happen — which matches the openat calls in the strace above (Masau\314\210stu\314\210). On byte-preserving filesystems (ext4 and friends) NFD and NFC are simply different paths, so the scaffold lands in a parallel decomposed-form directory tree and the CLI still exits 0.

That also explains why this is Linux-specific: HFS+ forces NFD at the filesystem layer and APFS is normalization-insensitive on lookup, so on macOS both forms resolve to the same entry and the bug is masked.

Two notes for whoever picks this up:

1. The durable fix is arguably upstream in modern-tar (NFD-normalizing tar entry names for comparison is defensible; rewriting the destination path's Unicode form is not) or in @bluwy/giget-core's usage of it — a create-astro-side NFC relocation works as a mitigation, but any other consumer of the extraction path stays affected.
2. The exploration branch triagebot/fix-17381 already contains a working create-astro-side mitigation plus a unit test (packages/create-astro/test/units/relocate-nfd.test.ts) that nobody has turned into a PR yet.

[kcabdussamed]

Thank you so much for the incredibly fast investigation and fix! I was honestly starting to question my sanity before diving into the strace logs. 😅

I actually ran into this bug while setting up the documentation for a custom compiled language project I'm working on called saQut. We are using Astro Starlight for the docs (which is an amazing tool, by the way!), but this Unicode/ext4 nightmare caught us off guard.

It's still in the early stages, but if anyone on the team is interested in structural programming languages or compiler development experiments, feel free to check it out:
🌐 Website: saqut.com
💻 GitHub: github.com/saqutlang/saqut

Thanks again for saving Linux users from this hidden path issue! 🚀