Skip to content

Troubleshooting

Fragment not found errors

If you get an error like Fragment resource 'my_fragment' not found, check that:

  1. The XML file exists in your fragments directory (default: resources/fragments/).
  2. The directory is registered in pubspec.yaml under flutter.assets.
  3. If the fragment is in a subdirectory, that subdirectory is also registered.
flutter:
  assets:
    - resources/fragments/
    - resources/fragments/auth/       # subdirectories need their own entries
    - resources/fragments/settings/
    - resources/values/

See Fragment Name Resolution for how XWidget resolves fragment names to files.

Resources not initialized. Call XWidget.initialize() first.

Something accessed Resources.instance or called XWidget.inflateFragment(...) before XWidget.initialize() finished. Common causes:

  • A widget tried to inflate a fragment during initState() on an app that hasn't finished initializing yet. await initialize() before runApp().
  • A static initializer or top-level code ran before main() awaited initialization.

Fix:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await XWidget.initialize(register: registerXWidgetComponents);  // await!
  runApp(MyApp());
}

Cloud deployment fails with version error

If xc cloud deploy rejects your version number, ensure it matches major.minor.patch, optionally followed by a pre-release identifier and/or a numeric build number. The build number must be a plain number — it maps to the Flutter build number in pubspec.yaml's version: x.y.z+N.

Accepted Not accepted
1.0.0 1.0
2.1.0+42 v1.0.0
1.0.0-beta 2.1.0+build.42
1.0.0-rc.1+7 0.0.1+hotfix

Cloud bundle not found or 403 errors

  • Confirm channel matches an existing channel (xc cloud channel list).
  • Confirm version is published to that channel — deployed alone is not enough (xc cloud deployment list -c <channel> shows what the channel serves; xc cloud publish makes a revision live).
  • Confirm storageKey is current — a rotation may have invalidated the old one (xc cloud project keys).

Cloud app works online, breaks offline on first launch

CloudResources falls back to local assets when both the network and local cache miss. On first launch offline, the cache is empty, so the asset fallback is the only option. Make sure your app ships baseline fragments and values in the asset bundle:

flutter:
  assets:
    - resources/fragments/
    - resources/values/

Populate these with a minimal working set of fragments so the app is functional on first offline launch. See Keep baseline assets in the app.

Analytics data not appearing

If you've deployed to XWidget Cloud but don't see analytics data:

  1. Verify that your resources provider is either CloudResources or LocalResources.withAnalytics — analytics are only enabled when a projectKey is configured on the provider.
  2. Check that the app has network access to analytics.xwidget.dev.
  3. Allow up to 15 minutes for events to flush from the device to the server. To force an immediate flush during debugging, background the app or call Analytics.shutdown().
  4. Verify you're querying the correct channel and time range in the CLI.
xc analytics renders -c production -r 7

See Analytics for how the analytics pipeline works.