One Letter Broke Four Toolchains. A Symlink Didn't Fix It.

Three Sessions, Four Broken Toolchains

When configuring an automated coding assistant or build workflow, one of the most effective safety constraints you can set is simple: "If you see something unexpected, stop and ask." On July 26, 2026, while working on a Flutter + .NET project, that guardrail triggered across three separate build sessions. Three times the automated assistant halted execution, flagging what appeared to be four completely unrelated failures across different tools:

• dart run build_runner build failed with package_config.json did not contain its own root package.
• flutter analyze broke down due to a Language Server Protocol (LSP) JSON-RPC framing crash.
• The Android Gradle Plugin (AGP) threw a path validation check error.
• A supporting .ps1 script failed to execute due to path literal encoding corruption.

Three work sessions, four distinct toolchains, four different error messages, and a separate search rabbit hole for each. Yet none of the error logs pointed to the actual common denominator. While I didn't log the exact SDK patch versions at the moment of failure, the root cause was a single uppercase non-ASCII character-an Ö-in the project's parent directory path.

The LSP framing failure in flutter analyze is a prime example of how deep these path leaks go. The official Language Server Protocol specification explicitly defines the header field: "The length of the content part in bytes." When a directory path containing multi-byte UTF-8 characters (like Ö) is injected into protocol payloads, the character count no longer matches the total byte length. The behavior observed-a sudden connection collapse during analysis-is consistent with framing misalignment when character count deviates from raw byte length. The path wasn't just an external string on disk; it was actively leaking into low-level protocol frames.

It Wasn't the Space. I Tested.

The immediate reaction to path failures on Windows is almost universally: "There must be a space in the directory name." It is a well-worn assumption in software engineering, but an assumption is a hypothesis, not a diagnosis. Removing spaces and non-ASCII characters simultaneously proves nothing about which change fixed the issue. If you alter two variables at once, a passing build won't tell you which one was breaking your toolchain.

To determine whether spaces were actually responsible, I ran a single-variable isolation test on the exact same project layout, executing flutter build apk:

• Pure ASCII path with spaces: EXIT = 0
• Identical path with an added Ö: EXIT = 255

One character changed. Everything else stayed identical.

C:\Dev\Proje\App Test\ -> EXIT = 0 (Build Passed)
C:\Dev\ProjeÖ\App Test\ -> EXIT = 255 (Build Failed)

This simple test highlighted a crucial debugging principle: "It's probably spaces" is a guess until you isolate the variables and measure them independently.

The Junction That Lied

Once the non-ASCII character was identified as the culprit, the standard workaround on Windows was the obvious next step: leave the physical files where they were, create a directory junction (a Windows reparse point similar to a symlink) from a clean ASCII path like C:\project to the actual directory, and execute the builds through the junction. When tested against the Dart and Flutter toolchains, it worked. Commands executed cleanly through the alias. Then I ran the Android build pipeline, and AGP crashed immediately.

The strangest part was the error output itself. AGP did not report C:\project-the junction path passed into the build invocation. Instead, it printed the underlying physical target path containing the Ö. The junction was meant to hide the non-ASCII character, but AGP exposed it anyway. The behavior points directly to how Java handles canonical path resolution. Java's File documentation describes canonical-path resolution as following symbolic links on UNIX platforms, though it doesn't explicitly detail Windows reparse points. I didn't audit AGP's internal source code, but the behavior I measured was unambiguous: AGP printed the physical target path instead of the junction path.

To verify whether this behavior was tied to the Java build environment, I ran a counter-test using the exact same junction setup: flutter build web. Executing flutter build web through the exact same junction, targeting the exact same physical directory, returned EXIT = 0. The web pipeline doesn't go through Gradle at all, so whatever the JVM does with reparse points never enters the picture - that's the difference I could point to, though I didn't instrument it.

[ C:\project (ASCII Junction) ]
|
+-----------+-----------+
|                       |
(Dart / Web)            (JVM / AGP)
|                       |
Bypasses Reparse        Reads Canonical Path
|                       |
v                       v
Passes (EXIT 0)         Exposes 'Ö' (EXIT 255)

The hypothesis held from both directions: the toolchain running on the JVM broke, while the non-JVM toolchain passed. This highlights a broader rule: you cannot assume an abstraction layer-whether a junction, a symlink, a