flutter runtime_error ai_generated true

Platform view assertion failure: vertical sync disabled

ID: flutter/platform-view-assertion-error

Also available as: JSON · Markdown · 中文
80%Fix Rate
82%Confidence
1Evidence
2023-06-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Flutter 3.10.0 active — — —
Flutter 3.13.9 active — — —
Android 12+ active — — —
iOS 16+ active — — —

Root Cause

Hybrid composition platform views cause assertion failure when the framework attempts to render with vertical sync disabled, often due to background isolate rendering or headless mode.

generic

中文

混合组合平台视图在框架尝试在垂直同步禁用时渲染时引发断言失败，通常是由于后台隔离渲染或无头模式。

Official Documentation

https://docs.flutter.dev/platform-integration/platform-views

Workarounds

  1. 85% success Ensure platform views are only created on the main isolate. Wrap platform view creation in a check: if (Isolate.current == Isolate.main) { /* create view */ } else { /* fallback or send to main isolate */ } 
    Ensure platform views are only created on the main isolate. Wrap platform view creation in a check: if (Isolate.current == Isolate.main) { /* create view */ } else { /* fallback or send to main isolate */ }
  2. 75% success Use virtual display mode instead of hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics in the AndroidManifest.xml metadata 
    Use virtual display mode instead of hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics in the AndroidManifest.xml metadata
  3. 70% success Disable headless mode in Flutter engine by setting --enable-headless-rendering=false in run arguments 
    Disable headless mode in Flutter engine by setting --enable-headless-rendering=false in run arguments

中文步骤

  1. Ensure platform views are only created on the main isolate. Wrap platform view creation in a check: if (Isolate.current == Isolate.main) { /* create view */ } else { /* fallback or send to main isolate */ }
  2. Use virtual display mode instead of hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics in the AndroidManifest.xml metadata
  3. Disable headless mode in Flutter engine by setting --enable-headless-rendering=false in run arguments

Dead Ends

Common approaches that don't work:

  1. Disable hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics 60% fail

    This reverts to virtual display mode which has its own rendering bugs and memory leaks, and does not address the root cause of the vertical sync issue.

  2. Set enableImplicitScrolling to false on all platform view widgets 80% fail

    Implicit scrolling is unrelated to vertical sync; this change breaks scrolling behavior without fixing the assertion.

  3. Upgrade to Flutter 3.16+ without any other changes 50% fail

    The assertion persists in newer versions if the platform view is still used in a background isolate context.