Shiply Flutter Dynamic FAQ

Common Questions

1. Exception: AOT snapshotter exited with code -9

This error is usually caused by one of the following:

1.1 macOS Security Restrictions

Description: macOS blocked Flutter engine execution.

Solution: Run the script in the SDK package. See the SDK integration guide section on macOS popup handling—run xattr_quarantine_inFlutter.sh in the SDK package.

1.2 Insufficient Android Heap Memory

Description: Out of memory when building large projects or during resource-intensive operations.

Solution: Increase heap memory in android/gradle.properties:

org.gradle.jvmargs=-Xmx8192M

2. Conch-Flutter Not Taking Effect

Conch takes effect only when enable: true in the project config and the app is built in release mode.

Typical logs when not active:

[ConchLoaderAPI] ConchLoader#load() Conch only takes effect in release build mode (currently in debug mode)
[ConchLoaderAPI] ConchLoader#init() Conch only takes effect in release build mode (currently in debug mode)

Troubleshooting: If you don't see detailed ConchLoader logs, Conch is not active. Then:

1. Try clearing caches
2. Verify configuration
3. Confirm release build mode
4. Check that the project path contains no Chinese characters—English paths are required

3. ConchCoreAPI.enableDebugLog() Debug Switch

Enabling debug mode outputs detailed Conch logs for troubleshooting.

Note: Debug mode affects app performance. Disable it before production release.

4. Image Asset Hot Update Not Working

Conch supports hot updating in-app image assets independently of code hot update. It uses a custom conchBundle to load images from local hot-update patch files first.

4.1 Automatic Update (No Extra Configuration)

If your app uses Flutter's Image.asset, SvgPicture.asset, or AssetImage to load images, Conch handles these automatically after applying a patch.

Add @PatchOnly on the corresponding function and build a patch to hot-update images. Conch loads new images from the updated patch first.

4.2 Manual Configuration (Custom Image Loading)

For non-standard or custom image loading, Conch cannot detect automatically. Replace the default AssetBundle with Conch's conchBundle:

Usage: Wrap the widget tree with DefaultAssetBundle so all resource loading uses this bundle:

DefaultAssetBundle(
  bundle: conchBundle,
  child: Widget(),
);

5. flutter build patch IconTreeShakerException

You may see this error when building patches:

Target aot_android_asset_bundle failed: IconTreeShakerException: ConstFinder failure: Unhandled exception:
Bad state: Empty input given.
#0      BinaryBuilder._checkEmptyInput (package:kernel/binary/ast_from_binary.dart:657:29)
#1      BinaryBuilder.readComponent.<anonymous closure> (package:kernel/binary/ast_from_binary.dart:681:7)
#2      Timeline.timeSync (dart:developer/timeline.dart:173:22)
#3      BinaryBuilder.readComponent (package:kernel/binary/ast_from_binary.dart:679:21)
#4      loadComponentFromBytes (package:kernel/kernel.dart:33:28)
#5      loadComponentFromBinary (package:kernel/kernel.dart:28:10)
#6      ConstFinder.findInstances (package:const_finder/const_finder.dart:199:35)
#7      main (file:///Users/xydevops/tgclubDevops/devops_single/workspace/flutter_engine/src/flutter/tools/const_finder/bin/main.dart:103:41)
#8      _delayEntrypointInvocation.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:295:33)
#9      _RawReceivePort._handleMessage (dart:isolate-patch/isolate_patch.dart:184:12)

To disable icon tree shaking, pass --no-tree-shake-icons to the requested flutter build command

Solution: Add --no-tree-shake-icons when building patches:

flutter build patch --no-tree-shake-icons

6. Exclude Changes from the Patch

To exclude changes from the patch, use the @PatchExclude() annotation on classes or methods.

Exclude a method:

@PatchExclude()
void someMethod() {
  // Changes to this method will not be included in the patch
}

Exclude an entire class:

@PatchExclude()
class SomeClass {
  // All changes to this class will not be included in the patch
}

7. View Diff Patch Differences and Propagation

When building diff patches, enable the following to inspect differences and propagated content:

conch:
  debugDiff: true  # Print diff content
  debugDiffCall: true  # Print content propagated from diff points

8. How to Build Patches for Multiple Versions?

Multi-version build: Place multiple conch_base_vxxxx.json base files under /conch_base/ in the project. The build outputs one patch per version.

Optional configuration:

conch:
  # Version numbers in conch_base_vxx.json files
  targetBaseVersions: v8.8.8.8, v9.8.8.8  # When building patches from multiple base files, specify which versions to build

9. Which Flutter Versions Does Conch Support?

Currently supports Flutter 3.16.9, 3.22.3, 3.24.5, 3.27.4, and 3.32.8.

Unsupported Scenarios

1. Hot Update of Non-Dart Code

Non-Dart code hot update is not supported.

2. Diff Patches Do Not Support Record Syntax

Diff patches do not support Record syntax.

3. Hot Update of Thread-Switching Code Not Supported

Hot update of Isolate.spawn, compute, and similar thread-switching code is not supported. New threads cannot read the Conch runtime instance. Use @PatchExclude to exclude Isolate call sites from patches.

Advanced Usage

1. Hot Update Content from dependencies Packages

By default, Conch hot update targets main project code. To hot update packages imported via dependencies, use moduleIncludes and hotfixModuleIncludes to expand the hot update scope.

1.1 moduleIncludes

moduleIncludes defines multi-module business scope and includes it fully in hot update scope. Configured modules have:

• Function hotfix scope: Functions in configured modules support independent hotfix
• API retention: APIs called in this scope during base package build are retained for post-update compatibility
• Page hot update propagation: Page hot updates automatically propagate patches to configured modules

Use case: Multi-module scenarios where dependencies packages should be included in automatic page hot update propagation beyond the main project.

conch:
  moduleIncludes: 
    - package:xxx
    - package:xxx

1.2 funcHookModuleIncludes

funcHookModuleIncludes also defines multi-module scope but limits page hot update propagation. Configured modules have:

• Function hotfix scope: Functions in configured modules support independent hotfix
• API retention: APIs called in this scope during base package build are retained
• Page hot update propagation limit: Page hot updates do not automatically propagate to these modules (main difference from moduleIncludes)

Use case:

• Support independent function hotfix for the module
• Avoid automatic page hot update propagation to prevent unnecessary updates, conflicts, or performance impact
• Large or infrequently changed modules that only need function-level hotfix

conch:
  funcHookModuleIncludes: xxx,xxx

Important notes:

• Main project is included by default; do not duplicate it here
• Configure this when building the base package so metadata and API retention are included