Troubleshooting

build_runner runs but no files are generated

1. Make sure your widget definition file is under lib/ (not bin/, test/, or example/)
2. Make sure the variable is final or const, declared at the top level (not inside a function or class)
3. Make sure the type is exactly AndroidWidget (not a typedef or alias)
4. Check build output for Found N AndroidWidget(s) in ... — if missing, the file was not scanned

Run with --verbose for more detail:

dart run build_runner build --verbose

"Build failed due to use of deleted Android v1 embedding"

Add to AndroidManifest.xml inside <application>:

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

Manifest not patched

Make sure both marker comments are present inside <application> in AndroidManifest.xml:

<!-- flutter_android_widgets:start -->
<!-- flutter_android_widgets:end -->

They must be:

• Inside <application> (not inside <activity>)
• Spelled exactly as above, including the spaces before the double-dash

Widget not appearing in the widget picker

1. Make sure flutter build apk (or flutter run) succeeded without errors
2. Verify the <receiver> entry is in AndroidManifest.xml between the markers
3. On some launchers you need to restart the launcher or reboot after installing a debug APK

Widget shows "Problem loading widget" on the home screen

1. Run flutter build apk --debug and verify it compiles
2. Check the generated Kotlin file has the correct package name at the top (should match your app's package)
3. Verify the layout XML only uses RemoteViews-compatible views (no custom views, no RecyclerView)
4. Check logcat for crash stacks:

adb logcat | Select-String "Widget|AppWidget|RemoteViews"

SharedPreferences data not appearing

Debug checklist:

1. Are you using HomeWidgetData.save()? (not raw SharedPreferences)
2. Does the key match an entry in your widget's dataKeys list?
3. Does the key match a \${key} placeholder in a WText?
4. Has the widget refreshed after saving? (Enable HomeWidgetData.autoUpdate = true, tap Refresh, or wait for the interval)
5. Does HomeWidgetData.read('yourKey') return the expected value in Flutter?

Style changes not appearing after hot restart

1. Make sure you passed widgets: [myWidget] to WidgetUpdater.initialize()
2. Make sure you used hot restart (Ctrl+Shift+F5), not hot reload — hot reload does not re-evaluate top-level final variables
3. Verify the widget on the home screen refreshed (you should see a flicker)

"Conflicting outputs" error from build_runner

Run with the delete flag:

dart run build_runner build --delete-conflicting-outputs

minWidth/minHeight change not taking effect

Size metadata is compiled into the APK and cached by the launcher at placement time. After changing:

dart run build_runner build
flutter run          # reinstalls APK

Then remove the widget from the home screen and re-add it. The launcher will read the new size from the freshly installed APK.

Button tap has no effect

1. Make sure the actionKey is non-empty and unique across all your widgets
2. Check that FlutterAndroidWidgetsChannel.kt was generated (in the kotlin/ directory)
3. Check that MainActivity.kt was patched to register the channel (look for FlutterAndroidWidgetsChannel.configure()
4. Check logcat for ACTION_<ACTIONKEY> broadcast not being received

Test coverage

The package includes 89 unit tests across 6 files:

Run all tests from the package root:

flutter test