Repository navigation
Description
1. Summary
Currently, Python returns the error message “Cannot create a file when that file already exists” when a folder, not solely a file, already exists.
If this problem isn’t fixable, it would be nice to add it to the documentation as a known issue to save users’ time.
2. MCVE
2.1. Testing environment
- Windows 11 26H2, Build 26300.9974
- Python 3.15.2
2.2. Python REPL
>>> from pathlib import Path
>>> Path("kira_goddess_folder").mkdir()
>>> Path("kira_goddess_folder").mkdir()
Traceback (most recent call last):
File "<python-input-7>", line 1, in <module>
Path("kira_goddess_folder").mkdir()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
File "D:\Scoop\apps\python\current\Lib\pathlib\__init__.py", line 1210, in mkdir
os.mkdir(self, mode)
~~~~~~~~^^^^^^^^^^^^
FileExistsError: [WinError 183] Cannot create a file when that file already exists: 'kira_goddess_folder'2.3. Incorrect error message
The Path.mkdir() method creates folders, not files. The “create a file” and “file already exists” phrases are incorrect in this case.
3. Why documentation changes, not fixing the problem?
It seems to me, the problem isn’t fixable in Python.
-
Python doesn’t use its own error messages for OS exceptions. Error messages depend on the system error codes.
-
The part of the comment on the related issue “Inconsistent exceptions thrown by
pathlib.Path.mkdiron different OSes”:In Windows, it's not possible to differentiate the two cases by error code alone, so unfortunately
Path.mkdir()tries to create the parent path when it contains a non-directory component, and thus a nestedFileExistsErrorexception is raised. -
Windows has the error message “Cannot create a file when that file already exists” for the system error code 183. The error message contains “file”, not “file or folder” or “file or directory”.
4. Proposed changes
A note at least such as the one below in the section FileExistsError of the Python documentation:
Note
On Windows, Python returns the error message “Cannot create a file when that file already exists” if a folder, not solely a file, already exists. This is a known problem that exists because of Windows limitations.
5. Best practices of known issues
For example, see the parts of the section “Known issues” of the official GitHub Style guide:
(…) known issues explain problems that people will encounter.
If a known issue applies to a specific article, document it in that article.
The goal of documenting an issue without a workaround is to help people confirm that the issue exists and save them time searching for a solution that doesn't exist yet after GitHub has already determined there isn't a workaround.
Flagging the problem described in this issue as a known issue could save my time and may save time of other Python users in the future.
Thanks.
Linked PRs
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsTodo
Activity
makwana-akshat commentedon Nov 20, 2026
i would like to solve this issue. assign/
makwana-akshat commentedon Nov 20, 2026
I've submitted a documentation-only fix for this issue in PR #162333.
The change adds a note to the
FileExistsErrordocumentation explaining that, on Windows, the operating system may return "Cannot create a file when that file already exists" even when attempting to create a directory.I also wanted to ask whether it would be worth addressing the error message itself rather than only documenting the behavior.
I understand that the message originates from Windows (
ERROR_ALREADY_EXISTS) and that changing it in CPython could have broader implications.Would a more descriptive error message specifically for directory-creation operations be feasible and desirable, or is documenting the existing behavior the preferred solution?
If maintainers think a runtime change would be appropriate, I'd be happy to investigate it separately.
Thanks!