Skip to content

gh-162326: Clarify Windows FileExistsError message for directories - #162333

Open
makwana-akshat wants to merge 1 commit into
python:mainfrom
makwana-akshat:docs/gh-162326-fileexistserror
Open

makwana-akshat wants to merge 1 commit into
python:mainfrom
makwana-akshat:docs/gh-162326-fileexistserror

Conversation

@makwana-akshat

@makwana-akshat makwana-akshat commented Nov 20, 2026 •

Copy link
Copy Markdown

Summary

Clarify the Windows-specific FileExistsError message when attempting to create a directory that already exists.

On Windows, the operating system may report "Cannot create a file when that file already exists" even when the operation involves a directory.

This PR adds a short note to the FileExistsError documentation explaining this behavior and referencing OSError.strerror.

Changes

  • Add a Windows-specific note in Doc/builtins/exceptions.rst.
  • No changes to runtime behavior.

Testing

  • git diff --check upstream/main — passed.
  • Verified that the branch contains only one documentation commit.
  • Confirmed that only Doc/builtins/exceptions.rst was modified.
  • Documentation build not run locally.

Closes #162326

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #36050432 | 📁 Comparing 421e3ae against main (e0d0f2e)

  🔍 Preview build  

1 file changed
± builtins/exceptions.html

@makwana-akshat

Copy link
Copy Markdown
Author

I've added a documentation note explaining why Windows may report "Cannot create a file when that file already exists" even when the operation involves creating a directory.

I also wanted to ask whether it would be worth improving the actual error message rather than only documenting the behavior.

I understand that the message comes from the Windows operating system (ERROR_ALREADY_EXISTS), so changing it in CPython may have broader implications.

Would it be feasible and appropriate to provide a more descriptive error message specifically for directory-creation operations, or is documenting the existing behavior the preferred approach?

If a runtime change is considered appropriate, I'd be happy to investigate and work on it separately.

I'd appreciate the maintainers' guidance. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

docs(FileExistsError): improve the documentation when a folder already exists

1 participant