flutter · vashworth · Apr 17, 2026 · Apr 29, 2026 · Apr 29, 2026 · Apr 30, 2026
@@ -21,6 +21,10 @@ import '../base/utils.dart';
 import '../base/version.dart';
 import '../build_info.dart';
 import '../convert.dart';
+import '../flutter_plugins.dart';
+import '../macos/swift_package_manager.dart';
+import '../plugins.dart';
+import '../project.dart';
 import '../reporting/reporting.dart';
 
 final _settingExpr = RegExp(r'(\w+)\s*=\s*(.*)$');
@@ -391,6 +395,17 @@ class XcodeProjectInterpreter {
   /// The stderr subscription for the Swift package fetch process.
   StreamSubscription<String>? _swiftPackageFetchStderrSubscription;
 
+  /// Resets the Swift package fetch process by killing it if it's running and clearing the
+  /// process and subscriptions.
+  Future<void> _resetSwiftPackageFetchProcess() async {
+    _swiftPackageFetchProcess?.kill();
+    _swiftPackageFetchProcess = null;
+    await _swiftPackageFetchStdoutSubscription?.cancel();
+    await _swiftPackageFetchStderrSubscription?.cancel();
+    _swiftPackageFetchStdoutSubscription = null;
+    _swiftPackageFetchStderrSubscription = null;
+  }
+
   /// Prefetches Swift packages for the given Xcode project.
   ///
   /// If a process is already running from a previous Flutter command, kill it before starting
@@ -399,11 +414,14 @@ class XcodeProjectInterpreter {
   ///
   /// If [quiet] is false, it will print a spinner while the command is running and print logs of
   /// what Swift packages are being fetched.
+  ///
+  /// If [force] is true, it will run the process even if it's already been run before.
   Future<void> prefetchSwiftPackages(
     String projectPath, {
     required Directory buildDirectory,
     bool quiet = true,
     bool waitForCompletion = true,
+    bool force = false,
   }) async {
     Status? status;
     try {
@@ -416,6 +434,9 @@ class XcodeProjectInterpreter {
         ),
         '-resolvePackageDependencies',
       ];
+      if (force) {
+        await _resetSwiftPackageFetchProcess();
+      }
       if (_swiftPackageFetchProcess == null) {
         // Check if process is already running from a previous Flutter command. If it is, kill it
         // so we don't have the process running twice. When this process is run twice, it'll cause
@@ -472,6 +493,21 @@ class XcodeProjectInterpreter {
         await _swiftPackageFetchStderrSubscription?.cancel();
       });
       if (exitCode != 0) {
+        final stderrString = stderrBuffer.toString();
+
+        final FlutterProject project = FlutterProject.fromDirectory(
+          _fileSystem.directory(projectPath).parent,
+        );
+        final List<Plugin> plugins = await findPlugins(project);
+        final String? swiftPackageManagerError = SwiftPackageManager.parsePluginError(
+          stderrString,
+          pluginNames: plugins.map((p) => p.name).toList(),
+        );
+
+        if (swiftPackageManagerError != null) {
+          _logger.printError(stderrString);
+          throwToolExit(swiftPackageManagerError);
+        }
         throwToolExit('Xcode failed to resolve Swift Package Manager dependencies:\n$stderrBuffer');
       }
     } finally {

@@ -403,4 +403,51 @@ class SwiftPackageManager {
       manifestContents.replaceFirst(oldSupportedPlatform, newSupportedPlatform),
     );
   }
+
+  static final List<_SwiftPMPluginErrorMatcher> _errorMatchers = <_SwiftPMPluginErrorMatcher>[
+    _SwiftPMPluginErrorMatcher(
+      // Example: target 'plugin_a' in package 'plugin_a' is outside the package root
+      pattern: RegExp(r"target '([^']+)' in package '[^']+' is outside the package root"),
+      message: (RegExpMatch match) =>
+          'Flutter plugin "${match.group(1)}" has an incorrectly configured Package.swift file.\n'
+          'Please contact the plugin maintainers for assistance.',
+    ),
+    _SwiftPMPluginErrorMatcher(
+      // Example: /path/to/plugin_a/Package.swift:25:17: error: expected ',' separator
+      pattern: RegExp(r'([^\/]+)\/Package\.swift:\d+:\d+: error:'),
+      message: (RegExpMatch match) =>
+          'Flutter plugin "${match.group(1)}" has an incorrectly configured Package.swift file.\n'
+          'Please contact the plugin maintainers for assistance.',
+    ),
+    _SwiftPMPluginErrorMatcher(
+      // Example: unknown package 'some-package' in dependencies of target 'plugin_a'
+      pattern: RegExp(r"unknown package '[^']+' in dependencies of target '([^']+)'"),
+      message: (RegExpMatch match) =>
+          'Flutter plugin "${match.group(1)}" has an incorrectly configured Package.swift file.\n'
+          'Please contact the plugin maintainers for assistance.',
+    ),
+  ];
+
+  /// Parses a Swift Package Manager error message and returns a guided error
+  /// message if the error matches a known pattern.
+  static String? parsePluginError(String? message, {required List<String> pluginNames}) {
+    if (message == null || message.isEmpty) {
+      return null;
+    }
+    for (final _SwiftPMPluginErrorMatcher matcher in _errorMatchers) {
+      for (final RegExpMatch match in matcher.pattern.allMatches(message)) {
+        final String? packageName = match.group(1);
+        if (packageName != null && pluginNames.contains(packageName)) {
+          return matcher.message(match);
+        }
+      }
+    }
+    return null;
+  }
+}
+
+class _SwiftPMPluginErrorMatcher {
+  const _SwiftPMPluginErrorMatcher({required this.pattern, required this.message});
+  final RegExp pattern;
+  final String Function(RegExpMatch match) message;
 }
@@ -227,13 +227,35 @@ class SwiftPackageManagerIntegrationMigration extends ProjectMigrator {
         }
       }
 
+      try {
+        // When migrating for the first time, this will be the first time packages are downloaded
+        // and may take a while.
+        await _xcodeProjectInterpreter.prefetchSwiftPackages(
+          _xcodeProject.hostAppRoot.path,
+          buildDirectory: _fileSystem.directory(
+            _platform.buildDirectory(config: _config, fileSystem: _fileSystem),
+          ),
+          quiet: false,
+          force: true,
+        );
+      } on Exception catch (e) {
+        throw _PrefetchSwiftPackageException(e.toString());
+      }
+
       // Get the project info to make sure it compiles with xcodebuild
       await _xcodeProjectInterpreter.getInfo(
         _xcodeProject.hostAppRoot.path,
         buildDirectory: _fileSystem.directory(
           _platform.buildDirectory(config: _config, fileSystem: _fileSystem),
         ),
       );
+    } on _PrefetchSwiftPackageException catch (e) {
+      restoreFromBackup(schemeInfo);
+      throwToolExit(
+          'An error occurred when adding Swift Package Manager integration:\n'
+          '  ${e.message}\n\n'
+          '$kDisableSwiftPMInstructions'
+      );
     } on Exception catch (e) {
       restoreFromBackup(schemeInfo);
       if (optionalOnly) {
@@ -248,8 +270,7 @@ class SwiftPackageManagerIntegrationMigration extends ProjectMigrator {
         throwToolExit(
           'An error occurred when adding Swift Package Manager integration:\n'
           '  $e\n\n'
-          'Swift Package Manager is currently an experimental feature, please file a bug at\n'
-          '  https://github.com/flutter/flutter/issues/new?template=01_activation.yml \n'
+          'Please file a bug at https://github.com/flutter/flutter/issues/new?template=01_activation.yml \n'
           'Consider including a copy of the following files in your bug report:\n'
           '  ${_platform.name}/Runner.xcodeproj/project.pbxproj\n'
           '  ${_platform.name}/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme '
@@ -1430,3 +1451,12 @@ class ParsedProject {
   final String identifier;
   final List<String>? packageReferences;
 }
+
+class _PrefetchSwiftPackageException implements Exception {
+  _PrefetchSwiftPackageException(this.message);
+
+  final String message;
+
+  @override
+  String toString() => message;
+}