A black or blank flutter_scene view usually has one of eight causes. On Android, check first that AndroidManifest.xml has the EnableFlutterGPU meta-data set to true. Without it the build succeeds and the app shows nothing. The other seven are below.

This is for Flutter developers whose 3D view renders nothing, renders black, or fails on one platform only. It reflects flutter_scene 0.20.0 to 0.24.3 and Flutter 3.47, as of October 2026. Most of these fixes come from failures we hit while building 3D apps on the GrowApps builder.

In short:

  • A green Android build proves nothing about Flutter GPU.
  • A scene may remain blank while its resources and model load.
  • Two imports clash: Material and the vector_math Matrix4.
  • Surfaces the sun misses stay black without an environment.

Find your symptom first

Match what you see to the likely cause, then jump to that fix.

Symptom Likely cause Section
Blank on Android, fine on web Flutter GPU flag missing Fix 1
Black for a few seconds Engine still starting Fix 2
Error before the first frame Engine not initialised Fix 3
Exception naming your .glb Asset not declared Fix 4
Scene draws, but very dark No environment light Fix 5
Compile errors on Material Import clash Fix 6
Matrix4 type error Wrong vector_math Fix 7
Nothing, no error Size or camera Fix 8

Fix 1: enable Flutter GPU on Android and iOS

Flutter GPU is off by default outside the web. Add this inside <application> in android/app/src/main/AndroidManifest.xml:

<meta-data
                  android:name="io.flutter.embedding.android.EnableFlutterGPU"
                  android:value="true" />

On iOS and macOS, add the FLTEnableFlutterGPU key set to true in Info.plist. In our tests, flutter build apk printed a successful build without the Android line, and the app opened to nothing. The flutter_scene README lists the line for every platform.

Fix 2: wait before you judge the first frames

The first frames are blank while the engine loads its shaders and resources. On the web, our first render took 263 ms, and a model can take a few seconds to parse. Show a progress indicator until loading finishes, and wait a few seconds before you judge a screenshot.

Fix 3: await initializeStaticResources first

Scene.initializeStaticResources() must finish before you create any geometry or material. Create a CuboidGeometry or a PhysicallyBasedMaterial too early and it fails. Put it at the top of your loading function:

Future<void> boot() async {
                await Scene.initializeStaticResources();
                scene.add(await Node.fromGlbAsset('assets/models/ship.glb'));
              }

Wrap the whole function in try and show the error on screen. A silent failure looks exactly like a black scene.

Fix 4: declare the model under assets

Node.fromGlbAsset throws when the file is not in the app bundle, even if it is right there in your project folder. Add the folder to pubspec.yaml:

flutter:
                assets:
                  - assets/models/

Then do a full restart, not a hot reload. New assets and new packages need a rebuild. The Flutter assets guide explains bundling.

Fix 5: give physically based materials an environment

A physically based material needs ambient light from an environment. Without it, anything the sun misses renders black, and a scene lit from behind looks like a black silhouette. In version 0.20.0 there is no ambient light object, so we bake a simple gradient sky into the scene's environment once. Newer versions add a default studio environment.

Also check for unlit materials. They ignore every light, so a scene built from them stays flat however you light it. Our lighting guide has working values.

Fix 6: hide Material from the Flutter import

package:flutter/material.dart and package:flutter_scene/scene.dart both export a class named Material. Import Flutter like this in your scene file:

import 'package:flutter/material.dart' hide Material;
              import 'package:flutter_scene/scene.dart';

Fix 7: use vector_math, not vector_math_64

Node.localTransform takes the Matrix4 from package:vector_math/vector_math.dart. Flutter re-exports the vector_math_64 version, which is a different class with the same name. The analyzer error names the same class twice, which is confusing. Add vector_math to your dependencies and import it with a prefix, such as as vm, for every vector and matrix in scene code.

Fix 8: check the size and the camera

A CustomPaint with no size draws nothing. Give the 3D view bounded constraints, such as an Expanded, a SizedBox or StackFit.expand. Then check the camera. If it sits inside the model, or looks away from it, you see only the background. Models exported in centimeters are 100 times too big for glTF's meters, so the camera ends up inside them.

How GrowApps avoids these

GrowApps adds the Android Flutter GPU line to every project when it prepares an Android build.

The builder agent's 3D starter awaits the engine before building anything, imports Flutter with hide Material, uses the vm. prefix for every vector, and shows a progress indicator and any error on screen.

It is also told to judge a scene only after the first frames have loaded. You can build a 3D app with GrowApps, and its starter handles most of these from the first build.

Test the flag on a phone now

If you ship Android, open your AndroidManifest.xml and search for EnableFlutterGPU. If it is missing, add it and rebuild. Then install the app on a real device, because emulators can fall back to a different renderer. For publishing next, see how to publish an app to Google Play.

Sources and further reading