Symbolication/Deobfsucation

Deobfuscate Dart stack traces and symbolicate native crashes from your Flutter app by uploading symbol files for Android and iOS with the Luciq CLI.

Deobfuscating Dart Crashes

In order to start deobfuscating Dart related crashes, you'll first need to follow the steps in the following URL to obfuscate your app: https://docs.flutter.dev/deployment/obfuscate

Uploading Symbol Files with Luciq CLI

The easiest way to upload symbol files for both Android and iOS is to use the Luciq CLI tool.

1

Install Luciq CLI

Install the Luciq CLI globally using Dart:

Terminal

dart pub global activate luciq_cli

Make sure the Dart global bin directory is in your PATH. If not, add it:

Terminal

# For macOS/Linux
export PATH="$PATH":"$HOME/.pub-cache/bin"

# For Windows
set PATH=%PATH%;%LOCALAPPDATA%\Pub\Cache\bin

2

Set up your credentials

You can provide your credentials in multiple ways:

Option 1: Environment Variables

Terminal

export LUCIQ_APP_TOKEN=your_app_token_here
export LUCIQ_API_KEY=your_api_key_here

Option 2: local.properties file Create a local.properties file in your project root:

local.properties

LUCIQ_APP_TOKEN=your_app_token_here
LUCIQ_API_KEY=your_api_key_here

Option 3: Pass as command-line arguments (shown in next step)

Reach out to our support team to get your API_KEY if you don't have one.

3

Upload symbol files

Run the upload command from your Flutter project directory:

Terminal

# Upload all symbols (searches current directory recursively)
luciq upload-symbols

# Upload from a specific directory
luciq upload-symbols --symbols-path /path/to/symbols

# Upload with explicit credentials
luciq upload-symbols --token YOUR_APP_TOKEN --api_key YOUR_API_KEY

# Upload with native sourcemaps (includes Android mapping.txt and iOS DWARF files)
luciq upload-symbols --enable-native-sourcemaps

# Upload with verbose logging to see detailed progress
luciq upload-symbols --verbose-logs

The CLI will automatically:

• Detect platform from filenames (.android or .ios)
• Read app version from pubspec.yaml
• Group and upload files by platform
• Find your app token from source files if not provided

For more options and advanced usage, run luciq upload-symbols --help

How Symbol File Upload Works

The Luciq CLI automatically detects and groups your symbol files:

• Files containing .android in their name are uploaded to the Android endpoint
• Files containing .ios in their name are uploaded to the iOS endpoint

Example: If your symbols folder contains:

• app.android-arm.symbols
• app.android-arm64.symbols
• app.ios-arm64.symbols

The CLI will:

1. Create one zip with all .android files → upload as Android platform
2. Create another zip with all .ios files → upload as iOS platform

Uploading with the standalone Luciq CLI

If you already use the standalone Luciq CLI (the luciq-cli Ruby gem) in your pipeline, it can upload Flutter symbol files too — zip your Dart symbol files per platform, then:

Terminal

luciq upload flutter-ios-sourcemap dart-symbols-ios.zip \
  --slug my-app --mode production --version-name 1.0.0 --version-code 1

luciq upload flutter-android-sourcemap dart-symbols-android.zip \
  --slug my-app --mode production --version-name 1.0.0 --version-code 1

It also covers native dSYMs, ProGuard/R8 mappings, and NDK .so files. See Uploading Symbol Files.

Manual Upload Using API

If you prefer to upload symbol files manually using the API, you can use the following endpoints:

Important: When uploading via API, symbol files must be packaged as a ZIP file with all symbol files in the root directory (no subfolders). The archive must be a .zip file format.

Android Symbol Upload

1

Fetch the symbol file

Obtain the symbol file for your Android build and create a ZIP file containing all symbol files in the root directory (without any subfolders).

Example structure:

symbols.zip
├── app.android-arm.symbols
├── app.android-arm64.symbols
└── app.android-x86.symbols

Do NOT include folders inside the ZIP.

2

Get your API_KEY

Reach out to our support team to get your API_KEY.

3

Upload the mapping file

Upload the mapping file using the following endpoint:

cURL

curl --location --request POST 'https://api.luciq.ai/api/web/public/flutter-symbol-files/android' \
--header 'Accept: */*' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept-Encoding: gzip, deflate, br' \
--form 'file=@"/path/to/symbols.zip"' \
--form 'application_token="YOUR_APP_TOKEN"' \
--form 'api_key="YOUR_API_KEY"' \
--form 'app_version_name="1.0.0"' \
--form 'app_version_code="1"'

Parameters:

• file: Path to your symbols ZIP file
• application_token: Your Luciq application token
• api_key: Your API key
• app_version_name: Your app version (e.g., "1.0.0")
• app_version_code: Your app build number (e.g., "1")

iOS Symbol Upload

1

Fetch the symbol file

Obtain the symbol file for your iOS build and create a ZIP file containing all symbol files in the root directory (without any subfolders).

Example structure:

symbols.zip
├── app.ios-arm64.symbols
└── app.ios-x86_64.symbols

Do NOT include folders inside the ZIP.

2

Get your API_KEY

Reach out to our support team to get your API_KEY.

3

Upload the mapping file

Upload the mapping file using the following endpoint:

cURL

curl --location --request POST 'https://api.luciq.ai/api/web/public/flutter-symbol-files/ios' \
--header 'Accept: */*' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept-Encoding: gzip, deflate, br' \
--form 'file=@"/path/to/symbols.zip"' \
--form 'application_token="YOUR_APP_TOKEN"' \
--form 'api_key="YOUR_API_KEY"' \
--form 'app_version_name="1.0.0"' \
--form 'app_version_code="1"'

Parameters:

• file: Path to your symbols ZIP file
• application_token: Your Luciq application token
• api_key: Your API key
• app_version_name: Your app version (e.g., "1.0.0")
• app_version_code: Your app build number (e.g., "1")

Native Crash Symbolication

For native iOS and Android crashes, you'll need to upload additional symbol files.

1

iOS Native Symbolication

For iOS native crashes and dSYM symbolication, follow the iOS documentation:

Symbolication | iOS | Luciq Docsdocs.luciq.ai

iOS Symbolication Guide

You can also use the --enable-native-sourcemaps flag with the Luciq CLI to automatically upload iOS DWARF files.

2

Android Native Deobfuscation

For Android native crashes and ProGuard/R8 mapping files, follow the Android documentation:

Deobfuscation for Android | Android | Luciq Docsdocs.luciq.ai

Android Deobfuscation Guide

You can also use the --enable-native-sourcemaps flag with the Luciq CLI to automatically upload the Android mapping.txt file.