Skip to content

[path_provider] Document null vs UnsupportedError return semantics #11793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
auto-submit merged 2 commits into from
Jun 15, 2026
Merged

[path_provider] Document null vs UnsupportedError return semantics #11793

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63f858f
[path_provider] Document null vs UnsupportedError return semantics
theprantadutta May 27, 2026
8491953
Address review: fix CHANGELOG nesting, bump versions
theprantadutta May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions packages/path_provider/path_provider/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
* Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
* Updates README to reflect currently supported OS versions for the latest
versions of the endorsed platform implementations.
* Documents the difference between a `null` return and an `UnsupportedError`
from `getDownloadsDirectory`.

@gemini-code-assist gemini-code-assist Bot May 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Inserting this bullet point here accidentally changes the nesting of the subsequent bullet point. The sub-bullet * Applications built with older versions of Flutter... (on lines 8-9) was meant to be nested under * Updates README..., but now it is nested under this new bullet point.

To preserve the correct hierarchy, please move this new bullet point to the end of the ## NEXT section (after the nested bullet point) or place it before the * Updates README... bullet point.

* Applications built with older versions of Flutter will continue to
use compatible versions of the platform implementations.

Expand Down
9 changes: 7 additions & 2 deletions packages/path_provider/path_provider/lib/path_provider.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,8 +217,13 @@ Future<List<Directory>?> getExternalStorageDirectories({
/// The returned directory is not guaranteed to exist, so clients should verify
/// that it does before using it, and potentially create it if necessary.
///
/// Throws an [UnsupportedError] if this is not supported on the current
/// platform.
/// Returns `null` when the current platform supports the concept of a
/// downloads directory but no such directory is currently available. For
/// example, on Linux this can happen when `xdg-user-dir` is not installed
/// or fails when called.
///
/// Throws an [UnsupportedError] when the current platform has no concept of
/// a downloads directory at all.
Future<Directory?> getDownloadsDirectory() async {
final String? path = await _platform.getDownloadsPath();
if (path == null) {
Expand Down
2 changes: 2 additions & 0 deletions packages/path_provider/path_provider_platform_interface/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
## NEXT

* Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
* Documents the implementation contract for `null` versus `UnsupportedError`
return semantics on `getDownloadsPath`.

## 2.1.2

Expand Down
8 changes: 8 additions & 0 deletions .../path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,14 @@ abstract class PathProviderPlatform extends PlatformInterface {

/// Path to the directory where downloaded files can be stored.
/// This is typically only relevant on desktop operating systems.
///
/// Implementations should return `null` when the platform supports the
/// concept of a downloads directory but no such directory is currently
/// available (for example, on Linux when `xdg-user-dir` is not installed
/// or fails when called).
///
/// Implementations should throw an [UnsupportedError] when the platform
/// has no concept of a downloads directory at all.
Future<String?> getDownloadsPath() {
throw UnimplementedError('getDownloadsPath() has not been implemented.');
}
Expand Down