Common Errors

Solutions to frequently encountered errors when using the Game Framework CLI and Flutter SDK.

CLI Authentication Errors

"Not authenticated" or "401 Unauthorized"

Error:

Error: Not authenticated. Run `game login` first.

Causes:

You have not logged in yet
Your session token has expired
The GAME_API_KEY environment variable is not set in CI/CD

Solutions:

# Log in interactively
game login

# Or set an API key for non-interactive use
export GAME_API_KEY=your_api_key_here

# Verify authentication is working
game workspace list

"Invalid API key"

Error:

Error: Invalid API key. Check your GAME_API_KEY environment variable.

Causes:

The API key was copied incorrectly (extra whitespace, truncated)
The key has been revoked or rotated

Solutions:

# Check the variable is set and has no extra whitespace
echo "$GAME_API_KEY"

# Generate a new API key from the Game Framework dashboard
# Then update your environment
export GAME_API_KEY=new_key_here

"Token expired"

Error:

Error: Authentication token has expired. Please log in again.

Solution:

# Re-authenticate
game login

For CI/CD pipelines, use GAME_API_KEY instead of interactive login. API keys do not expire unless explicitly revoked.

Build Errors

"Unity not found"

Error:

Error: Unity Editor not found. Install Unity or set the path in .game.yml.

Causes:

Unity is not installed
Unity is installed in a non-standard location
The Unity version in your project does not match what is installed

Solutions:

# Check if Unity is accessible
which unity

# Specify the Unity path explicitly in .game.yml

engines:
  unity:
    project_path: ../MyUnityProject
    unity_path: /Applications/Unity/Hub/Editor/2022.3.0f1/Unity.app

"Export failed" during `game export`

Error:

Error: Unity export failed with exit code 1

Causes:

Compilation errors in the Unity project
Missing platform build support module in Unity Hub
Scenes not included in Unity Build Settings

Solutions:

Open the Unity project in Unity Editor and fix any compilation errors
Install the required platform module via Unity Hub (e.g., Android Build Support, iOS Build Support)
Verify that your scenes are added in Unity > File > Build Settings > Scenes In Build
Run the export with verbose output for more detail:

game export unity --platform android --verbose

"Build settings not configured"

Error:

Error: No scenes found in build settings for platform android

Solution:

Open Unity Editor, go to File > Build Settings, and add your scenes to the Scenes In Build list. Then retry:

game export unity --platform android

"Wrong Unity version"

Error:

Error: Project requires Unity 2022.3.x but found 2021.3.x

Solution:

Install the correct Unity version via Unity Hub, or update your project to be compatible with your installed version. You can specify the exact editor path in .game.yml:

engines:
  unity:
    unity_path: /Applications/Unity/Hub/Editor/2022.3.20f1/Unity.app

Sync Errors

"Export directory not found" during `game sync`

Error:

Error: Export directory not found at ../MyUnityProject/Exports/android

Causes:

game export was not run before game sync
The export_path in .game.yml does not match where Unity actually exported

Solutions:

# Run export first
game export unity --platform android

# Then sync
game sync unity --platform android

Verify your .game.yml paths:

engines:
  unity:
    export_path: ../MyUnityProject/Exports  # Must match actual export location

"Target path conflict"

Error:

Error: Target path android/unityLibrary already exists and contains modifications

Solution:

Delete the target directory and re-sync:

rm -rf android/unityLibrary
game sync unity --platform android

"Version conflict" during sync

Error:

Error: Local version 1.0.0 conflicts with synced artifact version 1.1.0

Solution:

Update the version in .game.yml to match, or re-export with the correct version:

version: 1.1.0

game export unity --platform android
game sync unity --platform android

SDK Errors

"GameWidget: No engine plugin registered"

Error:

Exception: No engine plugin registered for GameEngineType.unity.
Did you call UnityEnginePlugin.initialize()?

Solution:

Initialize the engine plugin before runApp():

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  UnityEnginePlugin.initialize();  // Must be called before runApp
  runApp(MyApp());
}

"Failed to send message: Engine not ready"

Error:

Error: Failed to send message - engine is not ready

Causes:

Attempting to send a message before onEngineCreated fires
The engine was disposed or quit

Solution:

Always wait for the engine to be created before sending messages:

GameWidget(
  engineType: GameEngineType.unity,
  onEngineCreated: (controller) {
    // Safe to send messages here
    controller.sendMessage('GameManager', 'Start', 'data');
  },
)

Or check readiness before sending:

if (await _controller?.isReady() ?? false) {
  await _controller!.sendMessage('Target', 'Method', 'data');
}

"Message stream closed unexpectedly"

Error:

Error: Bad state: Stream has already been listened to

Solution:

Use a single listener or use asBroadcastStream() if you need multiple listeners:

final broadcastStream = controller.messageStream.asBroadcastStream();

broadcastStream.listen((msg) { /* handler 1 */ });
broadcastStream.listen((msg) { /* handler 2 */ });

Engine crashes on dispose

Causes:

Sending messages after calling dispose() or quit()
Not cancelling stream subscriptions before dispose

Solution:

class _GameScreenState extends State<GameScreen> {
  GameEngineController? _controller;
  StreamSubscription<GameEngineMessage>? _subscription;

  @override
  void dispose() {
    _subscription?.cancel();
    _controller?.dispose();
    super.dispose();
  }
}

Platform-Specific Errors

iOS: "Framework not found UnityFramework"

Error:

ld: framework not found UnityFramework

Causes:

game sync was not run for iOS
The framework path in .game.yml does not match the Xcode project

Solutions:

# Sync iOS framework
game sync unity --platform ios

# Verify the framework exists
ls ios/UnityFramework.framework

If the framework exists but Xcode cannot find it, check that the framework search path is correct in your Xcode project settings.

iOS: Code signing errors

Error:

Error: Signing for "UnityFramework" requires a development team

Solution:

Open ios/Runner.xcworkspace in Xcode and set the development team for both the Runner target and any embedded frameworks. You may also need to update the bundle identifier.

Android: "NDK not found"

Error:

Error: Android NDK not found. Required for Unity Android builds.

Solution:

Install the Android NDK via Android Studio > SDK Manager > SDK Tools > NDK (Side by side). Unity Android builds require the NDK for native library compilation.

Android: "minSdkVersion mismatch"

Error:

Manifest merger failed: uses-sdk:minSdkVersion 16 cannot be smaller than version 22

Solution:

Update your android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 22  // Required by Game Framework
    }
}

WebGL: "Out of memory"

Error:

RuntimeError: memory access out of bounds

Causes:

Default WebGL memory allocation is too small for your game
Large assets or textures exceeding browser memory limits

Solutions:

In Unity, go to Player Settings > WebGL > Memory Size and increase the allocation. Also consider:

Compressing textures for WebGL builds
Reducing asset sizes
Using asset streaming instead of bundling everything

Network and Connection Errors

"Connection timeout" during publish

Error:

Error: Connection to api.gameframework.dev timed out

Solutions:

# Check connectivity
curl https://api.gameframework.dev/health

# Retry with increased timeout
game publish --timeout 120

If you are behind a proxy or firewall, ensure api.gameframework.dev is allowlisted.

"Upload failed" for large artifacts

Error:

Error: Upload failed - request entity too large

Solution:

Large game artifacts may exceed default upload limits. Try:

Ensure you are only publishing enabled platforms
Strip debug symbols from release builds in Unity
Contact support if your artifacts legitimately exceed the limit for your plan

Configuration Errors

".game.yml not found"

Error:

Error: .game.yml not found in current directory

Solution:

Initialize a configuration file:

game init

Or ensure you are running CLI commands from the root of your Flutter project where .game.yml exists.

"Invalid .game.yml"

Error:

Error: Invalid configuration - missing required field 'engines'

Solution:

Validate and fix your configuration:

# Check for errors
game config validate

# View current config
game config show

Ensure your .game.yml has the required structure:

name: my_game_package
version: 1.0.0

engines:
  unity:
    project_path: ../MyUnityProject
    export_path: ../MyUnityProject/Exports
    platforms:
      android:
        enabled: true
        target_path: android/unityLibrary

Getting Help

If you are still stuck:

Run the failing command with --verbose for detailed output
Check the Debugging Guide for diagnostic tools
Search GitHub Issues for similar problems
Ask on GitHub Discussions
Email support@gameframework.dev with the full error output

When reporting issues, include the output of game config show, flutter --version, and the full verbose error output.

Next Steps

Debugging Guide - Verbose logging and diagnostic tools
FAQ - Frequently asked questions

On this page