Some md file is binary format, unreadable

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

in agent window, use the new feature: project.

  • in context area, the file:Project/notes.md is a binary format file, it can’t open, and can’t read.
  • in my project, the README.md file is also a binary file, can’t read.

Steps to Reproduce

upload a feature document, and ask it develop a software according to this file.

Expected Behavior

this file should be a text-file

Operating System

Windows 10/11

Version Information

Version: 3.20.21 (user setup)
VS Code Extension API: 1.128.0
Commit: f09fca384ceca23f7bf21f9c23655b162641d740
Date: 2026-09-13T19:02:51.781Z
Layout: Agent Window
Build Type: Stable
Release Track: Default
Electron: 42.10.0
Chromium: 148.0.7778.280
Node.js: 24.18.1
V8: 14.8.178.38-electron.0
xterm.js: 6.1.0-beta.291
OS: Windows_NT x64 10.0.22631

For AI issues: which model did you use?

Grok 4.6 high

For AI issues: add Request ID with privacy disabled

request id:
7b35fd95-e1a0-4ccc-934a-12f64da8f7ae

Does this stop you from using Cursor

No - Cursor works, but with this issue

Hey, thanks for the detailed report. This is a known issue we’re tracking: when creating a new file on Windows, the agent sometimes saves it as UTF-16 text without a byte-order mark (BOM). After that, both the Read tool and the viewer in the Agents window treat the file as binary, even though it’s just plain text in the wrong encoding.

To confirm, here are two quick checks:

  1. Open README.md in Cursor IDE.
  2. Look at the encoding label in the bottom-right of the status bar. What does it show UTF-8, UTF-16 LE, or something else. A screenshot would be ideal.

How to fix the files right now:

  1. Click the encoding label in the status bar.
  2. Choose Reopen with Encoding → UTF-16 LE. The text should become readable.
  3. Click the label again → Save with Encoding → UTF-8.
  4. For Project/notes.md, ask the Project agent in chat: “Use a shell command (iconv) to convert notes.md from UTF-16LE to UTF-8, then confirm you can read it.” Don’t ask it to rewrite the file using the normal edit tool, otherwise the encoding might come back.

To prevent this from happening again, make sure the files already in the repo are in UTF-8. New files often copy the encoding of existing ones. On Windows, it can also help to enable Beta: Use Unicode UTF-8 for worldwide language support in Settings > Time & Language > Language & Region > Administrative language settings > Change system locale.

Let me know what the encoding label shows and whether the fix worked.

There is not any encoding description label on the right bottom corner. as picture below:

so I can’t click the label to change encoding.

My solution

but I find a way to fix this problem, I ask Cursor to fix it, it give me a advice. After trying, it works fine.
following is the conversation:


ME:
the `README.md` file can’t read and can’t open. it is a binary file, try to analysis the reason, and tell me how to fix it.

Cursor:
README.md is not corrupted. It is UTF-16 Little Endian with no BOM, so tools treat it as binary.

Why it looks “binary”

A hex dump of the start of the file:

23 00 20 00 49 00 6D 00 61 00 67 00 65 00 ...
#     I     m     a     g     e     ...

Each ASCII character is followed by a 0x00 byte. The file is 1642 bytes and contains 605 null bytes.

That encoding is typical of:

  • “Unicode” / UTF-16 in Notepad or older Windows editors
  • PowerShell Out-File / Set-Content without -Encoding utf8 (Windows PowerShell 5.1 defaults to UTF-16 LE)
  • Some Visual Studio “Unicode” save options

There is no BOM (FF FE), so editors cannot guess UTF-16 and fall back to “binary / unknown”.

Effects:

Tool What happens
Cursor / this Read tool Refuses .md with NUL bytes
Git Treats the file as binary (git diff shows no text hunks)
GitHub Markdown is not rendered
VS / Notepad May refuse to open, or show garbage

The file is valid UTF-16 LE. Decoded, it is normal README text (# Image Cleaner, Chinese description, dotnet commands, etc.). It was already committed that way in 70b3989 (Add Image Cleaner WPF app...). Other project text files (.cs, .xaml, etc.) do not have this problem—only README.md.

How to fix

Re-save as UTF-8 (no BOM). That is what Git, GitHub, and Cursor expect for Markdown.

PowerShell (recommended):

$path = "d:\Document\***\project\Pic-BG-Cleaner\README.md"
$text = [System.IO.File]::ReadAllText($path, [System.Text.Encoding]::Unicode)
$utf8 = New-Object System.Text.UTF8Encoding $false
[System.IO.File]::WriteAllText($path, $text, $utf8)

Encoding.Unicode here means UTF-16 LE. $false means no UTF-8 BOM.

Avoid this in Windows PowerShell 5.1:

Set-Content README.md -Encoding utf8   # often writes UTF-8 *with* BOM
Out-File README.md                     # defaults to UTF-16 LE — this is likely how it broke

After converting:

  1. Reopen README.md in Cursor — it should be normal text.
  2. git diff README.md should show a real text diff, not Binary files differ.
  3. Commit the converted file when you are ready.

I am in Ask mode, so I cannot rewrite the file for you. Switch to Agent mode if you want this conversion applied automatically.


@deanrie

Your analysis is correct, your analysis is same as cursor, thanks

:rofl:

Great work, your fix is fully correct. The file really was UTF-16 LE without a BOM, so both the Read tool and the viewer in the Agents window treated it as binary. Your PowerShell command to re-save it as UTF-8 without a BOM is exactly what’s needed.

About the missing encoding label. It doesn’t show up because the file isn’t opening in a text editor at all. You only get the Open Anyway screen, so the PowerShell route is the right workaround here.

To prevent this from coming back:

  • Keep files in the repo as UTF-8. New files often inherit the encoding of existing ones, so one UTF-16 file can spread to others.
  • On Windows, it helps to enable Beta: Use Unicode UTF-8 for worldwide language support: Settings > Time & Language > Language & Region > Administrative language settings > Change system locale.
  • Don’t ask the agent to rewrite the file using the normal edit tool after converting. Prefer a shell command, otherwise the encoding can revert.

This is a known issue we’re tracking. Thanks for writing up the solution so clearly, it’ll definitely help other users with the same symptom.