# Platform view assertion failure: vertical sync disabled

- **ID:** `flutter/platform-view-assertion-error`
- **Domain:** flutter
- **Category:** runtime_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Flutter 3.10.0 | active | — | — |
| Flutter 3.13.9 | active | — | — |
| Android 12+ | active | — | — |
| iOS 16+ | active | — | — |

## Workarounds

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 */ }** (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 */ }
   ```
2. **Use virtual display mode instead of hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics in the AndroidManifest.xml metadata** (75% success)
   ```
   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** (70% success)
   ```
   Disable headless mode in Flutter engine by setting --enable-headless-rendering=false in run arguments
   ```

## Dead Ends

- **Disable hybrid composition by setting AndroidViewSurface.mode = AndroidViewSurfaceMode.graphics** — 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. (60% fail)
- **Set enableImplicitScrolling to false on all platform view widgets** — Implicit scrolling is unrelated to vertical sync; this change breaks scrolling behavior without fixing the assertion. (80% fail)
- **Upgrade to Flutter 3.16+ without any other changes** — The assertion persists in newer versions if the platform view is still used in a background isolate context. (50% fail)