Claude Code Windows encoding and path pitfalls

I have been using Claude Code on a Windows 11 company laptop for about 15 months. While the AI's coding logic rarely fails, I repeatedly hit a wall regarding encoding and file paths—the classic traps of a Korean Windows environment.

Claude Code Windows encoding and path pitfalls

Using PowerShell for text manipulation is a recipe for disaster. I tried using Get-Content and Set-Content to edit files, but the Korean characters broke. Even using Add-Content with explicit UTF-8 encoding didn't help; in July, I had to manually rewrite Korean text in a Python docstring because of this. The worst part was redirection: using echo with >> to append a line to a config file converted the entire file to UTF-16 and injected NUL characters, crashing the app on startup.

There is also a distinction between "looking broken" and "being broken." Once, Claude saw garbled Korean text in its own PowerShell output and tried to fix the console encoding, thinking it was a product bug. In reality, the file was perfectly fine—only the terminal output was corrupted. Now, if something looks off on screen, I always check the actual file bytes first.

Batch files present the opposite problem. .bat and .cmd files must be saved in CP949 (the legacy Korean Windows encoding). If saved as UTF-8, they fail to execute entirely. Adding chcp 65001 inside the batch file doesn't help, as it breaks the batch parser.

Python has its own set of traps. Because the console uses CP949, printing characters like em dashes or warning symbols causes encoding errors that crash the program. I fixed this by forcing the agent cron script output to UTF-8, but someone reverted it to CP949 in August, causing Korean notifications to vanish twice.

Then there is the python3 command. Typing python3 often opens the Microsoft Store instead of running Python because Windows uses app execution aliases as store redirectors. The reason python usually works is simply that the virtual environment appears first in the PATH. In processes with different PATH contexts, it still triggers the Store. To stop this, you must disable the alias or use the full path to the virtual environment's Python. I even set up a call-log trap to identify which process was triggering the redirector.

Testing and virtual environments add further friction. My pytest setup frequently hits "permission denied" errors in the default temporary folder, so I always provide the basetemp option. Additionally, since the project .venv is a Linux virtual environment for WSL, running it as if it were Windows Python leads to failure.

Finally, there was a deployment issue on the production PC. A git pull moved the HEAD but failed to write certain static JS files—likely because a server process was locking them or antivirus intervened. The version API reported the latest commit, but parts of the UI were broken. Since the repository was technically "correct," no test caught it. Now, if a report comes in that part of the screen is dead, I check static file URLs for 404s first. Recovery requires a git checkout of that specific folder; I also added a guard to log whether static files referenced by the template actually exist on disk during startup.

The workflow that finally worked

To avoid these issues, I shifted my entire environment logic. I use git-bash as my terminal and write all scripts called by Claude Code in bash. PowerShell is reserved strictly for Windows-specific tasks, and I never use it to edit text. For environment variables, I put them in the env section of Claude Code's settings.json to ensure consistent values regardless of the process context.

The rules are now simple: use Claude Code's built-in editing tools for files, keep batch files in ASCII (or CP949), force Python output to UTF-8, and always use the full path for Python. It took six recurring failures to get this right.

Related posts

This post is the English edition of a Korean write-up: 원문 보기

Comments

Post a Comment

Popular posts from this blog

npm command not found on Windows: fix the PATH

Image
I recently hit a wall while configuring my development environment on Windows. It's one of those subtle issues that can waste an afternoon if you don't know what to look for. Here's exactly how I diagnosed and fixed a 'command not found' error after a successful global install. The Problem I decided to add a markdown processing tool to my toolkit by running: npm install -g markdown-it-cli The terminal output confirmed the installation succeeded, displaying a message about added packages. Satisfied, I tried to use it by typing markdown-it-cli in the command line. Windows immediately responded with: 'markdown-it-cli is not recognized as an internal or external command, operable program or batch file.' This error means Windows looked through every folder in its search list and couldn't find an executable with that name. Attempts and Failures My initial reaction was to suspect the package itself might be broken. I tried running it using npx , wh...
Read more

Claude CLI 401 Unauthorized Refresh Token Issue

Symptom: claude commands fail with 401 Unauthorized and the message "refresh token was already used. Please log out and sign in again." Cause: The refresh token expired after being consumed by another session or a background process. Refresh tokens are single-use credentials. Fix: Run claude auth login to refresh authentication without running a logout command first. Why claude login alone did not clear the 401 I was running a pipeline command when every subsequent CLI call failed. The terminal returned this exact output: Error: 401 Unauthorized Message: "Authentication failed: refresh token was already used. Please log out and sign in again." Code: "AUTH_ERROR" The error text explicitly instructs me to log out. I spent roughly ten minutes searching the terminal for a logout function. The prompt only showed AUTH_ERROR . I assumed clearing old sessions was required first. That assumption blocked progress. The instructions in the error message ...
Read more

Tailscale without sudo: what userspace mode actually costs you

At first, I installed Tailscale on macOS knowing I did not have admin rights to write to system directories. The CLI package installed cleanly enough, landing entirely within my user space without triggering any permission errors or requiring elevated prompts. The installation process felt seamless, but the friction appeared immediately during usage. Every single command I typed required appending --socket=$HOME/.tailscale/tailscaled.sock to talk to the daemon. I found myself adding this flag to status checks, key generation, and connection queries across multiple sessions. The repetition was exhausting for a tool I expected to run in the background, turning routine operations into a chore. I eventually wrote a shell function to wrap this flag, allowing me to call tailscale directly without typing the socket path every time. This workaround saved my sanity but highlighted that userspace mode demands extra configuration just to use the CLI, and any automation scripts I maintained had...
Read more