Skip to content

[stable] [flutter_tools] Safely handle broken symlinks and existing files during plugin symlink creation - #194578

Merged
auto-submit[bot] merged 1 commit into
flutter:flutter-3.47-candidate.0from
flutteractionsbot:cp-stable-00bd76293961607746d30c051403d6d406b3e7c2
Oct 21, 2026
Merged

auto-submit[bot] merged 1 commit into
flutter:flutter-3.47-candidate.0from
flutteractionsbot:cp-stable-00bd76293961607746d30c051403d6d406b3e7c2

Conversation

@flutteractionsbot

@flutteractionsbot flutteractionsbot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

This pull request is created by automatic cherry pick workflow
Please fill in the form below, and a flutter domain expert will evaluate this cherry pick request.

Issue Link:

#190235

Impact Description:

In Flutter 3.47, _createPlatformPluginSymlinks crashes with an unhandled PathExistsException (errno = 183 on Windows / errno = 17 on macOS and Linux) during flutter build windows, flutter run -d windows, and flutter pub get whenever a non-link file or directory occupies a .plugin_symlinks/<plugin> path, and silently skips broken or outdated symlinks after plugin version upgrades. This is a top-10 tool crasher in 3.47.4 (8.2% of all flutter_tools crashes).

Changelog Description:

[flutter/190235] When running flutter pub get or building desktop apps with existing or broken plugin symlink entries, flutter_tools no longer crashes with a PathExistsException.

Workaround:

Users must manually run flutter clean or delete the windows/flutter/ephemeral/.plugin_symlinks and linux/flutter/ephemeral/.plugin_symlinks directories before running flutter pub get or building.

Risk:

What is the risk level of this cherry-pick?

  • Low
  • Medium
  • High

Test Coverage:

Are you confident that your fix is well-tested by automated tests?

  • Yes
  • No

Validation Steps:

  1. Create a Flutter project with a Windows or Linux desktop plugin.
  2. Replace an entry in windows/flutter/ephemeral/.plugin_symlinks/<plugin> with a regular file or directory, or point the symlink to a non-existent path.
  3. Run flutter pub get or flutter build windows and verify that the symlink is cleanly replaced without throwing a PathExistsException.

…ng plugin symlink creation (flutter#191496)

## Description

Fixes a crash during plugin symlink creation on Windows/Linux desktop
builds (`FileSystemException: Creation failed, OS Error: A file cannot
be created if it already exists., errno = 183` / `errno = 17`).

### Cause
Previously, `_createPlatformPluginSymlinks` checked `if
(link.existsSync()) continue;` before calling `link.createSync(path)`.
1. If a non-link entity (such as a regular directory or file from manual
extraction, git checkout, or previous builds) occupied the symlink path,
`Link.existsSync()` returned `false`. The tool then called
`link.createSync(path)`, crashing with `ERROR_ALREADY_EXISTS` (`errno =
183`) on Windows or `EEXIST` (`errno = 17`) on POSIX.
2. `Link.existsSync()` did not check if an existing symlink pointed to
the expected plugin target path. If a plugin's path changed (e.g. a
version upgrade in pub cache), existing symlinks pointing to outdated
paths were skipped.

### Fix
- Uses `typeSync(link.path, followLinks: false)` to inspect disk state
type-agnostically before symlink creation.
- Canonicalizes and compares `link.targetSync()` with `path`. If
matching, creation is skipped.
- Deletes stale or mismatched links via
`ErrorHandlingFileSystem.deleteIfExists(link)`, and removes conflicting
non-link entries before calling `link.createSync(path)`.

## Related Issues
* Fixes flutter#90028
* Related to flutter#131978
* Related to flutter#74227

## Tests
- `packages/flutter_tools/test/general.shard/plugins_test.dart`:
  - `createPluginSymlinks repairs broken symlinks without failing`
- `createPluginSymlinks replaces existing files with symlinks without
failing`
@flutteractionsbot flutteractionsbot added the cp: review Cherry-picks in the review queue label Oct 16, 2026
@flutteractionsbot

Copy link
Copy Markdown
Contributor Author

@bkonyi please fill out the PR description above, afterwards the release team will review this request.

@flutter-dashboard flutter-dashboard Bot added the CICD Run CI/CD label Oct 16, 2026
@flutter-dashboard

Copy link
Copy Markdown

This pull request was opened from and to a release candidate branch. This should only be done as part of the official Flutter release process. If you are attempting to make a regular contribution to the Flutter project, please close this PR and follow the instructions at Tree Hygiene for detailed instructions on contributing to Flutter.

Reviewers: Use caution before merging pull requests to release branches. Ensure the proper procedure has been followed.

@github-actions github-actions Bot added the tool Affects the "flutter" command-line tool. See also t: labels. label Oct 16, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

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.

Code Review

This pull request updates _createPlatformPluginSymlinks in flutter_plugins.dart to inspect disk entities without following links, allowing it to repair broken symlinks or replace conflicting non-link files/directories. Corresponding tests are added to verify these behaviors. Feedback points out that link.existsSync() is redundant after checking the entity type, and that relative symlink targets should be resolved against the symlink's parent directory rather than the current working directory to ensure correct canonicalization.

@bkonyi bkonyi changed the title [CP-stable][flutter_tools] Safely handle broken symlinks and existing files during plugin symlink creation [stable] [flutter_tools] Safely handle broken symlinks and existing files during plugin symlink creation Oct 16, 2026
@walley892 walley892 added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 21, 2026
@auto-submit
auto-submit Bot merged commit aa08f09 into flutter:flutter-3.47-candidate.0 Oct 21, 2026
12 checks passed
@flutteractionsbot
flutteractionsbot deleted the cp-stable-00bd76293961607746d30c051403d6d406b3e7c2 branch October 21, 2026 20:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

autosubmit Merge PR when tree becomes green via auto submit App CICD Run CI/CD cp: review Cherry-picks in the review queue tool Affects the "flutter" command-line tool. See also t: labels.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants