Common issues and solutions for flutter_carplay.

Cause: The Flutter engine isn't properly shared between the app and CarPlay.

Solution: Ensure you've set up the shared Flutter engine correctly:

1. Make flutterEngine a global variable in AppDelegate.swift
2. Use the same engine in SceneDelegate.swift
3. Call flutterEngine.run() in didFinishLaunchingWithOptions

See iOS Setup for the complete code.

Cause: The Flutter engine needs to run in headless mode.

Solution: Update your AppDelegate.swift:

let flutterEngine = FlutterEngine(
  name: "SharedEngine", 
  project: nil, 
  allowHeadlessExecution: true  // This is key!
)

And call forceUpdateRootTemplate() after setting the root template:

FlutterCarplay.setRootTemplate(rootTemplate: myTemplate, animated: true);
_flutterCarplay.forceUpdateRootTemplate();

Cause: The template was recreated but the item references are stale.

Solution: Use updateSections() instead of recreating the entire template:

// Good: Update sections in place
listTemplate.updateSections(newSections);

// Avoid: Recreating the template breaks item references
// FlutterCarplay.setRootTemplate(rootTemplate: newTemplate, animated: true);

Cause: The complete() callback isn't being called.

Solution: Always call complete() in your onPress handler:

CPListItem(
  text: 'Item',
  onPress: (complete, item) {
    // Do your work
    doSomething();
    
    // ALWAYS call complete() when done
    complete();  // Don't forget this!
  },
)

Cause: Usually a scene delegate configuration issue.

Solution:

1. Verify Info.plist has both scene configurations
2. Ensure SceneDelegate.swift exists and is properly set up
3. Clean build: flutter clean && flutter pub get && cd ios && pod install

Cause: Large images being loaded synchronously.

Solution:

• Use appropriately sized images (CarPlay display is small)
• PR #79 addresses background image loading (coming soon)
• Consider using asset images instead of URLs for critical UI

Cause: CarPlay connection state persists but Flutter engine is gone.

Solution: This is handled automatically in recent versions. If you still experience this:

1. Update to the latest version
2. Ensure you're using the shared engine pattern
3. Handle the connection callback to reinitialize state

Cause: Missing or incorrect Android Auto configuration.

Solution:

1. Verify automotive_app_desc.xml exists in res/xml/
2. Check AndroidManifest.xml has the meta-data entry
3. Restart Android Auto completely

See Android Auto Setup.

Cause: Plugin not registered or platform check missing.

Solution: Wrap CarPlay code in platform checks:

import 'dart:io';

if (Platform.isIOS) {
  final carplay = FlutterCarplay();
  // iOS CarPlay code
} else if (Platform.isAndroid) {
  final androidAuto = FlutterAndroidAuto();
  // Android Auto code
}

Cause: flutter_carplay doesn't provide Now Playing for Android Auto.

Solution: Use the audio_service package for Android Auto media integration. It provides native Now Playing support.

Cause: runtimeType.toString() is used internally, which breaks with obfuscation.

Status: Known issue (#28). Workaround: exclude flutter_carplay from obfuscation in your ProGuard rules.

Cause: The connection event fires before the listener is set up.

Solution: Check connection status after setting up the listener:

_flutterCarplay.addListenerOnConnectionChange((status) {
  // Handle changes
});

// Also check current status
final currentStatus = FlutterCarplay.connectionStatus;

1. Check the example app for reference
2. Search existing issues
3. Open a new issue with:
   • Flutter version (flutter --version)
   • Package version
   • Platform (iOS/Android)
   • Minimal reproducible code
   • Error logs