Title: docs(FileExistsError): improve the documentation when a folder already exists · Issue #162326 · python/cpython · GitHub
Open Graph Title: docs(FileExistsError): improve the documentation when a folder already exists · Issue #162326 · python/cpython
X Title: docs(FileExistsError): improve the documentation when a folder already exists · Issue #162326 · python/cpython
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 ...
Open Graph 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...
X 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...
Opengraph URL: https://github.com/python/cpython/issues/162326
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"docs(FileExistsError): improve the documentation when a folder already exists","articleBody":"### 1. Summary\n\nCurrently, Python returns the error message “Cannot create a file when that file already exists” when a folder, not solely a file, already exists.\n\nIf this problem isn’t fixable, it would be nice to add it to the documentation as a known issue to save users’ time.\n\n### 2. MCVE\n\n#### 2.1. Testing environment\n\n1. Windows 11 26H2, Build 26300.9974\n1. Python 3.15.2\n\n#### 2.2. Python REPL\n\n```Python traceback\n>>> from pathlib import Path\n>>> Path(\"kira_goddess_folder\").mkdir()\n>>> Path(\"kira_goddess_folder\").mkdir()\nTraceback (most recent call last):\n File \"\u003cpython-input-7>\", line 1, in \u003cmodule>\n Path(\"kira_goddess_folder\").mkdir()\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^\n File \"D:\\Scoop\\apps\\python\\current\\Lib\\pathlib\\__init__.py\", line 1210, in mkdir\n os.mkdir(self, mode)\n ~~~~~~~~^^^^^^^^^^^^\nFileExistsError: [WinError 183] Cannot create a file when that file already exists: 'kira_goddess_folder'\n```\n\n#### 2.3. Incorrect error message\n\n[**The `Path.mkdir()` method creates folders, not files**](https://docs.python.org/3/library/pathlib.html#pathlib.Path.mkdir). The “create a **file**” and “**file** already exists” phrases are incorrect in this case.\n\n### 3. Why documentation changes, not fixing the problem?\n\nIt seems to me, the problem isn’t fixable in Python.\n\n1. Python doesn’t use its own error messages for OS exceptions. Error messages [**depend on the system error codes**](https://docs.python.org/3/builtins/exceptions.html#os-exceptions).\n1. The part of the [**comment**](https://github.com/python/cpython/issues/87038#issuecomment-1093897961) on the related issue “Inconsistent exceptions thrown by `pathlib.Path.mkdir` on different OSes”:\n\n\t> 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.\n\n1. Windows has [**the error message “Cannot create a file when that file already exists” for the system error code 183**](https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--0-499-#:~:text=ERROR%5FALREADY%5FEXISTS,exists). The error message contains “file”, not “file or folder” or “file or directory”.\n\n### 4. Proposed changes\n\nA note at least such as the one below in [**the section `FileExistsError`**](https://docs.python.org/3/builtins/exceptions.html#FileExistsError) of the Python documentation:\n\n> [!NOTE]\n> 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.\n\n### 5. Best practices of known issues\n\nFor example, see the parts of [**the section “Known issues”**](https://docs.github.com/en/contributing/style-guide-and-content-model/troubleshooting-content-type#known-issues) of the official GitHub Style guide:\n\n> (…) known issues explain problems that people *will* encounter.\n>\n> If a known issue applies to a specific article, document it in that article.\n>\n> 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.\n\nFlagging 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.\n\nThanks.\n\n\n\u003c!-- gh-linked-prs -->\n### Linked PRs\n* gh-162333\n\u003c!-- /gh-linked-prs -->\n","author":{"url":"https://github.com/Kristinita","@type":"Person","name":"Kristinita"},"datePublished":"2026-11-20T13:37:54Z","url":"https://github.com/python/cpython/issues/162326"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:dd8b3077-8f2a-29ce-3fab-9f5891fa1880 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | EB14:2A5566:136617E:19799E7:6B01E945 |
| html-safe-nonce | e37e8b7a9655c057241bd8a3d9b05e77fea914229a83d2932af43e93aae32f33 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFQjE0OjJBNTU2NjoxMzY2MTdFOjE5Nzk5RTc6NkIwMUU5NDUiLCJ2aXNpdG9yX2lkIjoiMTE2OTI4NTQ5Mzk4NjM2ODY5IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | b86791b61e6d30cb8d90a02f2dd2c3684cf96e64bb7461e7e8d4d3e973090e60 |
| hovercard-subject-tag | issue:6512509338 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/cpython/162326/issue_layout |
| twitter:image | https://opengraph.githubassets.com/208c0ba329e64ba09f18639d58a29b8c09073a88d020e9ef248c3125945f04e6/python/cpython/issues/162326 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/208c0ba329e64ba09f18639d58a29b8c09073a88d020e9ef248c3125945f04e6/python/cpython/issues/162326 |
| og:image:alt | 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... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Kristinita |
| hostname | github.com |
| expected-hostname | github.com |
| None | 87e774ee7c6b3bee0490394e4d3e57ec9dbc956f74b87ea685dc8996c1676456 |
| turbo-cache-control | no-preview |
| go-import | github.com/python/cpython git https://github.com/python/cpython.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 81598961 |
| octolytics-dimension-repository_nwo | python/cpython |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 81598961 |
| octolytics-dimension-repository_network_root_nwo | python/cpython |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 423dbb54c5e7bfecc838eb387c1435eb3d0e760d |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width