Fixing "Build failed due to use of deprecated Android v1 embedding" in Flutter

Problem Overview

When building your Flutter application, you may encounter the error:

Build failed due to use of deprecated Android v1 embedding.

This error occurs because your Flutter project is using the outdated Android embedding v1, which was deprecated and eventually removed in newer Flutter versions. The error specifically points to your AndroidManifest.xml file containing the deprecated io.flutter.app.FlutterApplication reference.

Root Cause

The Android v1 embedding was Flutter's original integration method for Android apps. In newer Flutter versions (approximately since Flutter 1.12), the v2 embedding was introduced with significant improvements to plugin interoperability and app stability.

WARNING

The v1 Android embedding has been completely removed from recent Flutter versions. You must migrate to v2 embedding to build your app successfully.

Solutions

Solution 1: Update AndroidManifest.xml (Recommended)

The most straightforward fix involves modifying your AndroidManifest.xml file:

1. Change the application name reference:

   <!-- Before (v1 embedding) -->
   <application
       android:name="io.flutter.app.FlutterApplication"
       ...
   >

   <!-- After (v2 embedding) -->
   <application
       android:name="${applicationName}"
       ...
   >

2. Add the flutterEmbedding meta-data:

   <meta-data
       android:name="flutterEmbedding"
       android:value="2" />

   Place this inside your <application> tag.

Solution 2: Regenerate Android Platform Files

If manually updating files doesn't resolve the issue, you can regenerate the Android platform files:

# Remove the android directory
rm -rf android

# Regenerate Android platform files
flutter create --platforms=android .

TIP

Before deleting the android folder, make sure to back up any custom configurations you've added (like permissions, custom activities, or build configurations).

Solution 3: Update MainActivity

Ensure your MainActivity is properly configured for v2 embedding:

For Kotlin (MainActivity.kt):

package com.yourpackage.name

import io.flutter.embedding.android.FlutterActivity

class MainActivity: FlutterActivity() {
    // Optional: Add custom native code if needed
}

For Java (MainActivity.java):

package com.yourpackage.name;

import io.flutter.embedding.android.FlutterActivity;

public class MainActivity extends FlutterActivity {
    // Optional: Add custom native code if needed
}

Solution 4: Update Build Configuration

Ensure your build configuration is up to date in android/app/build.gradle:

android {
    compileSdkVersion 33 // Update to latest stable version
    // Other configuration...
    
    defaultConfig {
        targetSdkVersion 33 // Update to latest stable version
        // Other configuration...
    }
}

Temporary Workaround

If you need to build immediately but cannot complete the migration:

flutter run --ignore-deprecation

DANGER

This is only a temporary solution. The v1 embedding will not work in future Flutter versions, and you should complete the migration as soon as possible.

Verifying the Fix

After applying these changes, verify your migration was successful by:

1. Running flutter clean
2. Building your app with flutter build apk or flutter run
3. Checking that the deprecated embedding error no longer appears

Common Issues During Migration

• Missing build.gradle: Ensure you haven't accidentally deleted essential project files
• Plugin compatibility: Some older plugins might not support v2 embedding
• Custom native code: You may need to update any custom native code to work with the new embedding

Prevention

To avoid similar issues in the future:

• Keep your Flutter SDK updated regularly
• Create new projects periodically to compare configuration files
• Review release notes for breaking changes when updating Flutter

By following these steps, you should successfully migrate from the deprecated v1 Android embedding to the current v2 embedding, resolving the build error and ensuring your app remains compatible with future Flutter versions.