OSError in Python: Causes and Fixes

OSError is a general Python error for operating system related problems.

You will often see it when your code works with:

  • files
  • folders
  • paths
  • permissions

For beginners, the most important thing to know is this:

  • OSError usually means something is wrong with the path, file, folder, or access
  • the error message after OSError usually tells you what the real problem is

A quick way to start debugging is to check whether the path actually exists before using it.

import os

path = 'example.txt'

if os.path.exists(path):
    with open(path, 'r', encoding='utf-8') as file:
        print(file.read())
else:
    print('File not found:', path)

This helps with many common cases. A lot of OSError problems happen because the path is wrong, missing, or points to the wrong thing.

What OSError means

OSError is a broad error category for operating system related problems.

In practice, that usually means Python failed while trying to do something like:

  • open a file
  • create or remove a folder
  • rename a path
  • access a location without permission

Also, many common errors are part of the OSError family, including:

  • FileNotFoundError
  • PermissionError
  • IsADirectoryError
  • NotADirectoryError

So even if you do not see plain OSError, you may still be dealing with the same family of problem.

When OSError happens

OSError and its subclasses often happen in situations like these:

  • Opening a file that does not exist
  • Trying to write to a location without permission
  • Using a directory path where a file path is expected
  • Using a file path where a directory path is expected
  • Renaming, deleting, or listing invalid paths
  • Working with broken or platform-specific paths

For example:

  • open("missing.txt") may raise FileNotFoundError
  • opening a folder with open() may raise IsADirectoryError
  • writing to a protected location may raise PermissionError

Read the error message carefully

The traceback usually gives the best clue.

When you see an OSError, check these things first:

  • The error number, such as Errno 2 or Errno 13
  • The exact path shown in the error
  • Whether Python expected a file or a directory
  • Whether the problem is a missing path, wrong path, or blocked access

A few common examples:

  • Errno 2 often means the file or folder was not found
  • Errno 13 often means permission was denied
  • Errno 21 often means you used a directory where a file was expected
  • Errno 20 often means you used a file where a directory was expected

Common ways to fix OSError

Here are the most common fixes:

  • Make sure the file or folder really exists
  • Use the correct absolute or relative path
  • Check your current working directory
  • Use os.path.exists() before file operations when helpful
  • Make sure you have permission to read or write
  • Use os.path.join() to build paths safely
  • Do not try to open a directory with open()

Common causes include:

  • Wrong file path
  • Relative path used from the wrong working directory
  • Missing file or folder
  • No permission to access the path
  • Using a directory as if it were a file
  • Using a file as if it were a directory
  • Invalid characters or unsupported path format on the current system

If you are new to paths, see working with file paths in Python for a clearer explanation of relative and absolute paths.

Example: missing file causes an OSError family error

A missing file is one of the most common causes.

with open("missing_file.txt", "r", encoding="utf-8") as file:
    content = file.read()
    print(content)

Expected result:

FileNotFoundError: [Errno 2] No such file or directory: 'missing_file.txt'

In modern Python, this usually raises FileNotFoundError instead of plain OSError.

That is still part of the same error family. FileNotFoundError is a more specific subclass of OSError.

If this is your exact problem, see FileNotFoundError in Python: causes and fixes.

Example: handling OSError with try-except

If you want to handle several operating system related problems together, you can catch OSError.

try:
    with open("example.txt", "r", encoding="utf-8") as file:
        print(file.read())
except OSError as error:
    print("Something went wrong:")
    print(error)

This is useful when the exact subclass does not matter and you just want to show the error or fail safely.

For example, the output might be:

Something went wrong:
[Errno 2] No such file or directory: 'example.txt'

If you already know the likely problem, catching the specific error is better.

try:
    with open("example.txt", "r", encoding="utf-8") as file:
        print(file.read())
except FileNotFoundError:
    print("The file does not exist.")

Specific exceptions are easier to understand and usually easier to fix.

Debugging checklist

When you are not sure what is wrong, test the path directly.

import os

path = "example.txt"

print(os.getcwd())
print(os.path.exists(path))
print(os.path.isfile(path))
print(os.path.isdir(path))
print(repr(path))

What each line helps you check:

  • os.getcwd() shows your current working folder
  • os.path.exists(path) checks whether the path exists
  • os.path.isfile(path) checks whether it is a file
  • os.path.isdir(path) checks whether it is a directory
  • repr(path) shows the exact string, including hidden spaces or escape characters

These are the most useful debugging commands:

import os
print(os.getcwd())
print(os.path.exists(path))
print(os.path.isfile(path))
print(os.path.isdir(path))
print(repr(path))

You can also try a simpler path that you know exists. That helps you tell whether the problem is your code or the specific file location.

If you want a broader introduction to these tools, see the Python os module overview and os.path.exists() explained.

OSError vs specific errors

OSError is the broad parent category.

Specific subclasses give you a clearer description of what went wrong.

Common examples include:

  • FileNotFoundError
  • PermissionError
  • IsADirectoryError
  • NotADirectoryError

In general:

  • Catch OSError when you want to handle many OS-related problems together
  • Catch a specific subclass when you know the likely cause

For exact fixes, see:

FAQ

Is OSError the same as FileNotFoundError?

No. FileNotFoundError is a more specific subclass of OSError.

Should I catch OSError or FileNotFoundError?

Catch the specific error when you know the problem.

Catch OSError when you want to handle several operating system related errors together.

Why does my code work in one folder but not another?

The current working directory may be different, or the second location may have different files or permissions.

Can OSError happen without using files?

Yes. It can also happen with other operating system operations such as directories, process actions, or some path operations.

See also