Flutter Plugin CI Path Failure: Causes & Fixes

When a Flutter plugin fails to reproduce the device path in CI, the cause is almost always a mismatch between the plugin’s expected environment and the CI runner’s actual setup—most commonly path separators, missing symlinks, or stale caches. This article explains why this happens and provides concrete steps to diagnose and fix it, so your continuous integration builds work reliably.

Background: Flutter Plugin Structure and CI

Flutter plugins are packages that expose native code (Android, iOS, web, etc.) to Dart. During development, the Flutter tool generates a device path (e.g., android/app/src/main or ios/Runner) based on your local environment. In CI, the same plugin is built on a fresh virtual machine, often with a different operating system, file structure, or environment variables. The term “device path” refers to the absolute or relative path to the native platform source that the plugin expects. When this path is hard-coded or assumed, CI builds fail because the path doesn’t exist on the runner.

How the Device Path is Determined

The Flutter tool resolves plugin paths using a combination of the pubspec.yaml file, the platform folders inside the plugin package, and the current working directory. For example, a plugin with an android folder expects that folder to be present at the root of the package. In CI, the plugin is often fetched from a package repository (like pub.dev) or cloned from a git repository. If the plugin is not properly activated (e.g., flutter pub get not run), the path may point to a cached location that doesn’t match the runner’s file system.

Moreover, CI systems like GitHub Actions, GitLab CI, or Jenkins run on ephemeral machines. Any path that includes user-specific directories (e.g., /home/runner vs /Users/jenkins) will differ. The Flutter tool tries to be portable by using relative paths, but plugins that use native build scripts (Gradle, Xcode) may resolve absolute paths from environment variables like ANDROID_HOME or FLUTTER_ROOT.

Common Causes of Path Mismatch

• Hard-coded absolute paths in the plugin’s native code or build scripts (e.g., /Users/me/plugin).
• Missing symlinks: Some plugins create symlinks during setup (e.g., flutter create .), which may not be preserved in CI.
• Stale caches: CI runners often cache dependencies. If the plugin was previously built with a different path, the cache may hold an old reference.
• Platform-specific path separators: Windows uses backslashes, while Linux/macOS use forward slashes. A plugin that uses a hard-coded separator will fail on the other OS.
• Working directory differences: The CI script may run from a different directory than expected, causing relative paths to resolve incorrectly.

How to Diagnose the Issue

Start by reproducing the failure locally in a clean environment. Run the same commands as your CI script on a fresh clone of your repository. If it works locally, the issue is environment-specific. Then, in CI, add debug steps to print the current directory, the plugin path, and the resolved paths:

1. Add pwd and ls -la commands in your CI script before the build.
2. Enable verbose logging: flutter build apk --verbose (or flutter build ios --verbose) to see which paths are being used.
3. Check the generated .dart_tool/package_config.json to see the resolved plugin paths.
4. Compare the paths between your local machine and CI. Look for differences in drive letters, home directories, or symlink targets.

Fixes and Best Practices

Once you identify the cause, apply one or more of these fixes:

• Use relative paths in your plugin’s native code. For example, in Android Gradle files, use project.rootDir instead of absolute paths.
• Set environment variables consistently. Ensure FLUTTER_ROOT and ANDROID_HOME are set correctly in CI (often done via setup actions).
• Clean caches before build: flutter clean and remove .gradle and build folders.
• Use a consistent working directory: In CI, always cd to the repository root before running Flutter commands.
• Replace backslashes with forward slashes in path strings, or use Platform.pathSeparator in Dart code.
• For symlinks: In CI, run flutter pub get after checkout to regenerate symlinks (Flutter does this automatically).

Comparison: Local vs CI Environment

Local development typically uses a persistent machine with a fixed user profile. CI uses ephemeral containers or VMs. Key differences:

• User home directory: e.g., /home/runner vs /Users/yourname.
• Operating system: CI may use Linux while you develop on macOS or Windows.
• Pre-installed tools: CI may have a different version of Android SDK or Xcode.
• File permissions: CI may run as root or a service account, affecting symlink creation.

Understanding these differences helps you write portable build scripts. For instance, never assume the user name or home directory.

Preventing Future Failures

To avoid this problem recurring:

• Use a CI configuration that mirrors your local environment as closely as possible (e.g., same OS, same Flutter version).
• Pin your Flutter SDK version in CI (e.g., using subosito/flutter-action with a specific version).
• Run flutter doctor in CI to verify the environment is healthy.
• Store any path-dependent configuration in a dedicated file (like .env) and load it in both local and CI.
• Regularly update your CI images to match the latest Flutter requirements.

Frequently Asked Questions

Why does my plugin work locally but fail in CI?

Because CI uses a clean environment with different absolute paths, missing symlinks, or stale caches. The code may have hard-coded paths or rely on environment variables that aren’t set in CI.

How do I find the exact path that is failing?

Run your build with verbose logging (flutter build --verbose) and search for “path” or “directory” in the output. Also, print the current working directory and list the plugin folder in CI.

Should I use relative or absolute paths in my plugin?

Always use relative paths in your plugin code. Absolute paths are never portable. Use Dart’s Platform.pathSeparator or the path package to construct paths safely.

Can I fix this by changing my CI configuration?

Yes, often the fix is to set the correct environment variables (like FLUTTER_ROOT) or to run flutter pub get before building. Also, ensure you are in the correct working directory.

What if the plugin is third-party and I can’t modify it?

You can work around it by creating a symlink in CI that maps the expected path to the actual location, or by using a custom build script that sets the required environment variables. If the plugin is broken, consider reporting the issue to the maintainers.

Is this a Flutter bug?

Rarely. Most path failures are due to user code or CI configuration. Flutter’s tool is designed to be cross-platform, but it can’t compensate for hard-coded paths in your plugin.

Related

• IVR Caller Input & Routing: Key Facts
• Phono vs Line: Do You Need a Preamp?
• Pokemon Legends Z-A Evolution Guide: Triggers, Stones, Trades