Repository navigation
path_provider getDownloadsDirectory documentation doesn't say when it might return null #143238
Description
The getDownloadsDirectory function is defined as potentially returning null. The documentation talks about it potentially throwing an UnsupportedError if this is not supported on the current platform, and talks about the returned Directory maybe not existing, but doesn't say when it might return null. So it's not clear if this is a failure mode that one should handle, or what to do when it happens.
https://pub.dev/documentation/path_provider/latest/path_provider/getDownloadsDirectory.html
Activity
stuartmorgan-g commentedon Feb 9, 2024
The intent is that
UnsupportedErroris for platforms that don't implement this at all (e.g., a platform that has no concept of a download directory), whilenullwould mean that the implementation understands the concept, but that there's no such directory available.That distinction is probably not worth handling two different ways, especially since the null case should be very rare, so we could consider changing all the currently nullable methods to be non-nullable, and convert nulls from the platform interface to
MissingPlatformDirectoryException(and then documenting that).Hixie commentedon Feb 9, 2024
The docs also refer to the possibility of the path being valid but not existing, that's distinct from the case of the path not being available?
stuartmorgan-g commentedon Feb 9, 2024
Yes; for instance on Linux you could configure your XDG settings to say your Download directory is
~/thisdirectoryhasneverexisted, and thenpath_providerwould return that valid but non-existent path.Hixie commentedon Feb 10, 2024
What's an example of the path not being available? Something like Linux when no downloads directory has been configured at all?
stuartmorgan-g commentedon Feb 10, 2024
Right now you could get it by running on a Linux without
xdg-user-dir, or where that exists but fails when called.In theory iOS/macOS could return an empty array from the search, but I would be pretty surprised if that's possible in practice.
Hixie commentedon Feb 10, 2024
Cool. Those details would be great to include in the docs. Thanks for the explanations!
familan commentedon May 1, 2025
stuartmorgan-g commentedon May 1, 2025
@familan Please file a new issue; the example is separate from the Dart docs.
theprantadutta commentedon May 15, 2026
Hi @stuartmorgan-g @Hixie — would it be useful if I took this on? The maintainer responses upthread already lay out exactly what to add. My plan:
getDownloadsDirectoryinpath_provider/lib/path_provider.dartand the matching method onPathProviderPlatforminpath_provider_platform_interfaceto explain:UnsupportedErroris thrown when the platform has no concept of a "downloads directory"nullis returned when the platform supports the concept but no such directory is available (concrete example: Linux withoutxdg-user-dirconfigured, or where it fails when called)Directorymay not exist (the existing case, e.g. an XDG-configured directory pointing somewhere non-existent)Happy to defer if someone's already on this. Otherwise I'll open a PR and link back here.
[path_provider] Document null vs UnsupportedError return semantics (#…
github-actions commentedon Jul 14, 2026
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of
flutter doctor -vand a minimal reproduction of the issue.