Defined in header <filesystem>
class filesystem_error;
(since C++17)

The class std::filesystem::filesystem_error defines an exception object that is thrown on failure by the throwing overloads of the functions in the filesystem library.

cpp/error/exceptioncpp/error/runtime errorcpp/error/system errorstd-filesystem-filesystem error-inheritance.svg

Inheritance diagram


[edit] Member functions

constructs the exception object
(public member function) [edit]
replaces the exception object
(public member function) [edit]
returns the paths that were involved in the operation that caused the error
(public member function) [edit]
returns the explanatory string
(public member function) [edit]

Inherited from std::system_error

Member functions

returns error code
(public member function of std::system_error) [edit]
returns an explanatory string
(virtual public member function of std::system_error) [edit]

Inherited from std::runtime_error

Inherited from std::exception

Member functions

destroys the exception object
(virtual public member function of std::exception) [edit]
returns an explanatory string
(virtual public member function of std::exception) [edit]

[edit] Notes

In order to ensure that copy functions of filesystem_error are noexcept, typical implementations store an object holding the return value of what() and two std::filesystem::path objects referenced by path1() and path2() respectively in a separately-allocated reference-counted storage.

Currently the MS STL implementation is non-conforming: objects mentioned above are stored directly in the filesystem object, which makes the copy functions not noexcept.

[edit] Example

#include <system_error>
#include <filesystem>
#include <iostream>
int main()
    const std::filesystem::path from{"/nonexistent1/a"}, to{"/nonexistent2/b"};
    try {
        std::filesystem::copy_file(from, to); // throws: files do not exist
    catch(std::filesystem::filesystem_error const& ex) {
            << "what():  " << ex.what() << '\n'
            << "path1(): " << ex.path1() << '\n'
            << "path2(): " << ex.path2() << '\n'
            << "code().value():    " << ex.code().value() << '\n'
            << "code().message():  " << ex.code().message() << '\n'
            << "code().category(): " << ex.code().category().name() << '\n';
    // All functions have non-throwing equivalents
    std::error_code ec;
    std::filesystem::copy_file(from, to, ec); // does not throw
    std::cout << "\nnon-throwing form sets error_code: " << ec.message() << '\n';

Possible output:

what():  filesystem error: cannot copy file: No such file or directory [/nonexistent1/a] [/nonexistent2/b]
path1(): "/nonexistent1/a"
path2(): "/nonexistent2/b"
code().value():    2
code().message():  No such file or directory
code().category(): generic
non-throwing form sets error_code: No such file or directory