AI Coding Agent Windows Path Bugs: 6 Fixes
AI coding agent Windows path bugs come from code written for Linux. Six patterns to search for, the fix for each, and one prompt that audits a whole repo.
AI coding agent Windows path bugs almost always have the same root: the code was written, and often tested, in a Linux-style environment, then run on a Windows machine. Path separators, line endings, shell commands and letter case behave differently, and an agent that never saw the failure will not account for them. The app works in the agent's sandbox and breaks on your laptop with an error about a file that clearly exists.
You can find most of these by searching for six patterns. Each one below has a bad example, a fix, and a way to make the agent check its own work.
Bug 1: paths built with string slashes
The most common mistake is building a path by joining strings with /.
// breaks or behaves oddly on Windows
const file = baseDir + "/" + folder + "/" + name;
// works everywhere
const path = require("node:path");
const file = path.join(baseDir, folder, name);The Node documentation says path.join() joins the given segments using the platform-specific separator and then normalizes the result. It also says path.sep is \ on Windows and / on POSIX. Let the library do the joining and your code stops caring which one it is on. The same idea applies in other languages: Python's pathlib, for example, exists for this reason. You can read the details in the Node.js path documentation.
Bug 2: paths compared as strings
A check like file.startsWith("src/") fails when the path arrives as src\components\Button.tsx. If you need to compare, build paths with the same library first, or convert them to one form before comparing. Node offers path.posix and path.win32 for code that must handle one style on purpose, such as parsing a URL path rather than a file path.
Bug 3: letter case that only Linux enforces
On many Linux filesystems Button.tsx and button.tsx are two different files. On a default Windows setup they are the same. An agent working on Linux can write import "./button" for a file called Button.tsx, and it will fail there but pass on Windows, or the reverse when you move the project. If an import error mentions a file that "exists", compare the exact case in the name, the import and the git history.
Bug 4: shell commands in package scripts
Agents love scripts such as:
"scripts": {
"clean": "rm -rf dist && mkdir dist",
"build": "NODE_ENV=production vite build"
}Neither line runs in the default Windows command shell. Use portable tools instead, such as rimraf for deleting folders and cross-env for setting environment variables, or write the step as a small Node script. Ask the agent to replace every shell-specific command in package.json and to explain what each replacement does.
Bug 5: line endings in scripts
A shell script saved with Windows line endings can fail on Linux or in a container with an error that mentions a bad interpreter or a stray character. It usually happens when a file moves between environments without a rule. Add a .gitattributes file so git normalizes line endings the same way for everyone, and ask the agent to commit it. Tracked file hygiene is also why a good .gitignore matters, which we cover in AI coding agent gitignore mistakes.
Bug 6: tools that exist only where the agent ran
The agent tested with a command that happens to be installed in its environment, such as grep, sed, make or bash. On your machine it is missing. When an agent says "run this command", ask where it ran it. Our post on why AI writes code that does not work explains why an unverified environment is the usual culprit, and when an AI coding agent cannot run your build covers the case where it never ran anything.
One prompt to audit AI coding agent Windows path bugs
Audit this repository for cross-platform bugs on Windows. Do not change anything yet.
List every place that:
1. builds a file path by joining strings with "/" or "\\"
2. compares paths as strings
3. imports a file with different letter case than its real name
4. uses shell-only commands in package.json scripts or build files
5. relies on bash, grep, sed, make or other tools that Windows does not ship
6. adds scripts that could be saved with the wrong line endings
For each, give the file, the line, and the portable replacement. Then wait."Wait" matters. Review the list, then ask for the fixes in small commits so you can read each diff.
Catch them automatically
Do not rely on your own machine. If your project runs on GitHub Actions, add a Windows job to the test matrix so every push runs on both. Our guide to setting up a GitHub Actions pipeline with AI walks through a safe version. If you are choosing between running your agent in the cloud or on your own computer, cloud vs local AI coding agent explains why this problem shows up differently in each. For the broader picture, see our guide to AI coding tools.
Frequently asked questions
Why does my AI-generated code work in the sandbox but fail on Windows?
The sandbox is often a Linux environment, and the code relies on forward-slash paths, shell commands or case-sensitive file names that behave differently on Windows.
What is the safest way to build file paths in Node?
Use path.join() or path.resolve() rather than joining strings. Per the Node docs, path.join() uses the platform-specific separator and normalizes the result.
Do I need to tell the agent I am on Windows?
Yes, say so in the instructions file, along with the shell you use. It stops the agent from suggesting commands that only work elsewhere.
What do I do about CRLF and LF line endings?
Add a .gitattributes file that sets a consistent line-ending policy, and ask the agent to commit it. Check any shell scripts that were created on one system and run on another.
Can a CI job catch Windows bugs for me?
Yes. Running your tests on a Windows runner as well as a Linux one finds path and shell bugs on every push, before anyone installs the app.
How did this land?
About the author

Staff Engineer, Platform
Carlo works on the platform that turns prompts into running apps. He writes the engineering deep dives and the changelog notes worth reading.


