Skip to content

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

Description

@Kristinita

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

  1. Windows 11 26H2, Build 26300.9974
  2. 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.

  1. Python doesn’t use its own error messages for OS exceptions. Error messages depend on the system error codes.

  2. The part of the comment on the related issue “Inconsistent exceptions thrown by pathlib.Path.mkdir on 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 nested FileExistsError exception is raised.

  3. 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

Activity

  1. makwana-akshat commented on Nov 20, 2026

    @makwana-akshat

    i would like to solve this issue. assign/

  2. makwana-akshat commented on Nov 20, 2026

    @makwana-akshat

    I've submitted a documentation-only fix for this issue in PR #162333.

    The change adds a note to the FileExistsError documentation 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!

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    OS-windowsdocsDocumentation in the Doc dir

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions