Skip to main content
Flashduty supports multi-platform symbol file uploading and source mapping, helping developers restore obfuscated or minified error stacks back to readable original source code.
  • Web (JavaScript): Upload sourcemap files through Flashduty CLI
  • WeChat Mini Program: Upload the sourcemap.zip generated by miniprogram-ci get-dev-source-map through Flashduty CLI
  • HarmonyOS: Upload the ArkTS sourceMaps.map, optional nameCache.json, and native .so symbol files through @flashcatcloud/hvigor-plugin
  • Android: Automatically upload ProGuard/R8 mapping files and NDK symbol files through a Gradle plugin
  • iOS: Upload dSYM symbol files through Flashduty CLI
  • Flutter: Upload the Dart AOT symbol files (.symbols) from --split-debug-info with Flashduty CLI to restore obfuscated Dart stacks on Android. iOS native crashes use dSYMs, like standalone iOS apps
  • Electron: Upload Breakpad .sym symbol files through Flashduty CLI, matched to native crash stacks by module Debug ID. See Electron Error Symbolication
  • React Native: On Android, the SDK’s Gradle script uploads the JS bundle sourcemap during the release build. On iOS, upload main.jsbundle and main.jsbundle.map through Flashduty CLI (≥ 0.4.0) with sourcemaps upload-react-native. See Uploading React Native SourceMaps below
Users can view uploaded symbol files in the “Application Management” - “Source Code Management” menu, and generate scripts through the upload panel to execute uploads locally.

Generate SourceMap

Most modern build tools (such as Webpack, Rollup, or Vite) support generating SourceMap.
Enable SourceMap generation in webpack.config.js:
After building, the dist directory will contain bundle.js and the corresponding bundle.js.map file.

Upload SourceMap

Use Flashduty CLI to upload sourcemap files to the Flashduty server.
1

Install Flashduty CLI

Ensure Node.js is installed, then install through npm:
2

Configure Upload Parameters

Upload Source Code Configuration
In the “Application Management” - “Source Code Management” menu, click the “Upload Source Code” panel and fill in the following information:
string
required
Used to authenticate your identity
string
required
Application service name (for example, my-service)
string
required
Application release version (for example, 1.0.0)
string
required
Path prefix for minified files (for example, /assets)
string
Only needed for private deployments. On a private deployment the panel pre-fills the intake address issued by the deployment, and you can override it manually (protocol + domain, no path, for example, https://rum.example.com). Leave it empty to upload to Flashduty SaaS.
3

Execute Upload

Run the generated script in the project root directory:
For private deployments, prefix the command with the FLASHCAT_SOURCEMAP_INTAKE_URL environment variable to upload symbol files to a custom intake, for example, FLASHCAT_SOURCEMAP_INTAKE_URL=https://rum.example.com flashcat-cli sourcemaps upload ... (protocol + domain, no path). When unset, uploads go to Flashduty SaaS. Once “Custom Upload Endpoint” is filled in, the panel-generated command includes this variable automatically.
  • Ensure minified-path-prefix matches the actual deployed minified file path
  • After successful upload, you can view uploaded sourcemap files in “Application Management” - “Source Code Management”

Upload WeChat Mini Program SourceMap

After a WeChat Mini Program is released, production error stacks usually contain only transformed file paths and line and column numbers. You can first use miniprogram-ci get-dev-source-map to generate sourcemap.zip, then upload it through Flashduty CLI. After upload, Flashduty matches Mini Program error stacks by service name, version, and file path, then shows restored source code locations in error details.
1

Generate the Mini Program SourceMap archive

Run miniprogram-ci get-dev-source-map in the Mini Program project to generate an uploadable sourcemap.zip file. This file path is used as the --sourcemap-zip parameter in the upload command.The default zip layout produced by miniprogram-ci get-dev-source-map already satisfies the following requirements, so you usually do not need to repackage it:
  • Main-package .js.map entries are placed under the __FULL__/ directory, for example, __FULL__/app-service.js.map
  • Subpackage .js.map entries are placed under a directory named after the subpackage, for example, subpkg-a/chunk_0.appservice.js.map, and the directory name is recorded as the subpackage tag in metadata
  • Only entries with the .js.map suffix are processed; other files (README, source files) are silently ignored
  • If the zip contains no .js.map entries, the upload fails with No .js.map entries found in the sourcemap archive
Each .js.map may not exceed 50 MB decompressed; the aggregate decompressed size of the whole archive may not exceed 500 MB; the zip may not contain more than 5000 entries. Exceeding any of these limits returns HTTP 413.
2

Configure upload parameters

In “Application Management” - “Source Code Management”, switch to the “WeChat Mini Program” tab and click “Upload Source Code”. The upload panel generates the command from the form values.
string
required
Authenticates the upload request. The page prioritizes API Keys that the current account can access.
string
required
Mini Program service name, such as my-mp. Error parsing uses this value to match the service in error events.
string
required
Mini Program release version, such as 1.2.3. Error parsing uses this value to match the version in error events.
string
required
Path to the archive generated by miniprogram-ci get-dev-source-map, such as ./sourcemap.zip.
string
WeChat Mini Program appid, for example, wxbad3e0a65782821c. Used to disambiguate uploads when multiple Mini Programs share the same service + version. Optional when only one Mini Program is involved.
string
Shown only for private deployments. The panel pre-fills the intake address issued by your deployment, and you can override it manually (protocol + domain, no path, for example, https://rum.example.com). Leave it empty to upload to Flashduty SaaS. When set, the generated command prepends FLASHCAT_SOURCEMAP_INTAKE_URL=<endpoint>.
3

Execute upload

Run the generated command in the project root. --appid is optional and is omitted from the generated command when the field is empty:

Upload HarmonyOS symbols

HarmonyOS crash stacks can contain both ArkTS / JS frames and native .so frames. To restore both kinds in the console, upload these build artifacts:
  • sourceMaps.map: the primary ArkTS sourcemap bundle
  • nameCache.json: optional, used to restore obfuscated identifier names
  • Unstripped native .so files: used to symbolicate C/C++ crash stacks
In Application Management → Source Code Management → HarmonyOS, the upload panel asks for Service, Version, and API Key, then generates the matching hvigor configuration and upload command. service and version must exactly match what the application reports at runtime, otherwise the server cannot match the uploaded symbols to incoming crash events.
1

Install the hvigor plugin

Declare the plugin in the project’s hvigor/hvigor-config.json5 and let hvigor fetch it from npm:
hvigor/hvigor-config.json5
You can also run npm install -D @flashcatcloud/hvigor-plugin, but a HarmonyOS project root has no package.json, so run npm init -y first or npm installs into an unrelated project in a parent directory. See HarmonyOS SDK advanced configuration.
2

Register the plugin in hvigorfile.ts

Write the panel-generated service, version, and apiKey settings into hvigorfile.ts:
hvigorfile.ts
3

Run the upload after the build

Once the build artifacts are ready, run the upload task. --no-daemon is required when you configure the plugin from environment variables. Otherwise a reused hvigor daemon passes a stale environment, the API key reads as unset, and the upload is silently skipped:
  • Use 0.1.5 or later. 0.1.3 made the task depend on assembleHar, which doesn’t exist in a HAP module, so the build fails. 0.1.4 was withdrawn from npm and can’t be installed
  • On SaaS, omit endpoint — hvigor-plugin ≥ 0.1.3 defaults to https://ci.flashcat.cloud. Do not use the RUM ingest host browser.flashcat.cloud (it 404s). For a private deployment set FLASHCAT_SOURCEMAP_INTAKE_URL (requires ≥ 0.1.3) or pass endpoint explicitly
  • Native .so symbolication depends on the GNU build-id. The HarmonyOS NDK enables it by default; if your build pipeline disables it, add -Wl,--build-id explicitly
  • For the full HarmonyOS integration, symbol-upload, and compatibility details, continue with HarmonyOS SDK advanced configuration

Upload Android Symbol files

After Android apps use ProGuard/R8 for code obfuscation, class names and method names in error stacks are replaced with meaningless short names. By uploading mapping files, Flashduty can restore obfuscated stacks to original code. For apps containing NDK native code, NDK symbol files also need to be uploaded to restore C/C++ layer stacks.
1

Add Gradle Plugin

Add the Flashduty Android Gradle plugin to your app module’s build.gradle:
Kotlin DSL uses the same plugin ID:
2

Configure API Key

Provide the API key through Gradle properties, environment variables, or a project configuration file. CI pipelines commonly use environment variables:
You can also create a flashcat-ci.json file in the project root:
API Keys can be created and managed in the console’s “API Key Management” page.
3

Configure Upload Options

Add the flashcat block to your app module’s build.gradle. When fields are not set explicitly, the plugin reads versionName, versionCode, and the application ID from the Android build configuration.
By default the plugin selects the upload endpoint from site: CN uses ci.flashcat.cloud. For private deployments, set sourcemapEndpoint to a custom intake endpoint (supported since 1.2.0); if the value omits the /sourcemap/upload path it is appended automatically. The three configuration sources are resolved in this order of precedence: flashcat {} extension config > flashcat-ci.json > the FLASHCAT_SOURCEMAP_INTAKE_URL environment variable. Once a custom endpoint is set, site is only used as a fallback and no longer affects the actual upload URL.
4

Run Upload Tasks

After the build completes, run the Gradle tasks to upload symbol files:
The plugin creates uploadMapping<Variant> tasks for variants with obfuscation enabled. NDK symbol upload tasks are created when the project has a native build or when additionalSymbolFilesLocations is configured. If your project uses multiple flavors, run the upload task for each release variant.
NDK symbol files must be unstripped ELF files that contain a GNU build-id section.Symbol files are matched to crashes by GNU build-id. If a .so file has no build-id, the upload returns HTTP 400 with this message:
Common causes and fixes:
  • CMake Release builds strip symbols by default: CMake runs strip after linking when CMAKE_BUILD_TYPE=Release, which removes the .note.gnu.build-id section. Add the linker flag explicitly in CMakeLists.txt:
    Or apply it to the whole project:
  • Manual strip scripts: If your CI runs strip on .so files, upload the unstripped originals from obj/, not the stripped artifacts from libs/. Use the additionalSymbolFilesLocations setting to point to that path.
NDK native symbol files are identified in the API by event.type=ndk_symbol_file, distinct from ProGuard mapping files which use event.type=jvm_mapping_file. Custom upload integrations that do not use the Gradle plugin must pass the correct type field.

Upload iOS dSYM files

iOS apps generate dSYM (Debug Symbol) files during compilation, containing the debug symbol information needed to map memory addresses back to source code locations. After uploading dSYM files, Flashduty can restore addresses in crash stacks to readable function names, file names, and line numbers.
1

Install Flashduty CLI

Ensure Node.js is installed, then install through npm:
2

Obtain dSYM Files

dSYM files can be obtained from the following locations:
  • Xcode Local Build: Find .dSYM files in the Xcode Build Products directory
  • Xcode Archive: Export dSYMs through the Organizer window
  • App Store Connect: Download dSYMs from App Store Connect (requires enabling symbol upload in build settings)
3

Execute Upload

Upload dSYM files using Flashduty CLI:
You can also fill in parameters in the “Source Code Management” panel in the console to automatically generate the upload command.

Upload Flutter Symbol files

When a Flutter app is built with --obfuscate, symbols in Dart exception stacks are stripped, leaving only address information. Upload the Dart AOT symbol files (app.<platform>-<arch>.symbols) from --split-debug-info. Flashduty matches each file’s GNU build-id to the build ID in the stack and restores Dart stacks on Android.
1

Build with obfuscation to generate the symbol directory

Enable obfuscation in the Android build and specify the symbol output directory:
2

Configure Upload Parameters

In “Application Management” - “Source Code Management”, switch to the “Flutter” tab and click “Upload Source Code”. The upload panel generates the command from the form values.
string
required
Authenticates the upload request; corresponds to the FLASHCAT_API_KEY environment variable in the command.
string
required
The symbol directory specified by --split-debug-info, for example, ./debug-symbols.
string
required
Application service name, such as my-app. Keep it consistent with the service set at SDK initialization, so symbols are categorized by service in the console.
string
required
Application release version, such as 1.0.0. Keep it consistent with the releaseVersion set at SDK initialization.
string
Shown only for private deployments. The panel pre-fills the intake address issued by your deployment, and you can override it manually (protocol + domain, no path, for example, https://rum.example.com). Leave it empty to upload to Flashduty SaaS. When set, the generated command prepends FLASHCAT_SOURCEMAP_INTAKE_URL=<endpoint>.
3

Execute Upload

Run the generated command in the project root:
Dart stacks cannot be symbolicated on iOS. Flutter produces Mach-O symbol files for Apple targets, but Flashduty parses only the ELF format used on Android. An iOS .symbols upload is therefore rejected. iOS native crashes (Objective-C / Swift / C / C++) are unaffected: upload dSYMs to symbolicate them, the same as a standalone iOS app.If you ship both iOS and Android, you can still enable --obfuscate: Android Dart stacks resolve normally while iOS Dart stacks stay obfuscated. If readable iOS stacks matter more, leave --obfuscate off for that platform’s build.
Symbol files are matched to crash events by build ID; service and release-version do not participate in symbolication and only affect categorization and filtering in the console list. Symbol files support the arm, arm64, and x64 architectures, detected automatically from the .symbols filename. Every Dart code change produces a new build ID, so symbol upload must be part of every release build. For the full Flutter symbolication details, see Flutter SDK Advanced Configuration.

Uploading React Native SourceMaps

React Native JS error stacks are de-minified with sourcemaps. Like Flutter, a React Native app runs one JS codebase on top of Android/iOS native code. Sourcemaps for the two platforms are stored separately, so same-named bundles never overwrite each other. The server matches by the react-native type plus the platform (iOS / Android). In App Management → Source Maps, select the React Native tab; the upload panel generates the relevant script for the selected platform:

Android: upload at build time

On Android, the SDK’s bundled Gradle script performs the upload during the release build (it shells out to flashcat-cli with the bundle Metro just produced). Pin the service name and apply the script in android/app/build.gradle:
Then run the release build with the API key in the environment — the upload happens as part of the build:
The uploaded objects are index.android.bundle and its sourcemap. The SDK’s Metro configuration (Debug ID) is also wrapped with withDatadogMetroConfig; see React Native SDK integration.

iOS: upload after the build

iOS has no build hook, so the upload runs by hand after the release build. react-native-xcode.sh emits a sourcemap only when SOURCEMAP_FILE is set. Export it in the Xcode build phase “Bundle React Native code and images”, before react-native-xcode.sh:
Then install the CLI (≥ 0.4.0) and upload the bundle and its sourcemap:
  • The uploaded bundle file name must equal the name the app loads at runtime (index.android.bundle on Android, main.jsbundle on iOS). Symbolication matches stack frames by file name, so a bundle renamed with --bundle-output in CI will never be matched.
  • --release-version must equal the reported version (the SDK’s config.version override or its default), otherwise no match is found.
  • A wrong service name puts the upload under the wrong service, and both the Issue list and the symbol table stop lining up.
  • For the full React Native setup (including @flashcatcloud/mobile-react-native version requirements and private deployments), see React Native SDK Advanced Configuration.

Symbol file management

On the Flashduty platform, symbol file management is done through the “Application Management” - “Source Code Management” menu:

View source code in error tracking

RUM Error Tracking uses Web sourcemap files, WeChat Mini Program SourceMaps, Android mapping files, and iOS dSYM files to restore error stacks. Error details then show the original source locations.
1

Capture Errors

RUM SDK automatically captures application errors and sends error stack information to the server. Web scenarios include uncaught JavaScript exceptions, unhandled Promise rejections, console.error calls, and manually reported errors; native scenarios include crashes, exceptions, and stack information required for symbolication.
2

Associate Symbol Files

Flashduty matches file paths, line numbers, or addresses in the stack against your uploaded files: Web sourcemap files, WeChat Mini Program SourceMaps, Android ProGuard mapping files, Android NDK symbol files, or iOS dSYM files. When they match, it maps minified, obfuscated, or compiled locations back to the original source.Minified file stack:
Mapped source code:
3

View Error Details

In the Error Tracking module, click a specific error record to view:
  • Error message: for example, Something went wrong
  • Original stack: Mapped source code file path, line number, and column number
  • Context code: Display source code snippet near the error location
Code lines longer than 480 characters are clipped: the frame’s own line keeps a window around the reported column, other lines keep their head, and each cut end is marked with …. If the sourcemap’s sourcesContent is itself a minified bundle, every line you see is such a window rather than the full code around the frame.If a Mini Program stack isn’t resolved, the notice in error details links to the Mini Program type on the Source Code Management page. From there you can open the upload panel for that version’s sourcemap.zip.
4

Debug and Fix

Based on the mapped source code location, find the corresponding code directly in your local development environment, analyze the root cause, and fix it.

Best practices

Integrate upload commands in CI/CD pipelines to ensure automatic upload of Web sourcemap files or WeChat Mini Program sourcemap.zip with each release.GitHub Actions Example:
Use the --release-version parameter to match the application version number for easy tracking of specific version sourcemaps.
Delete sourcemap files before uploading resources to CDN to avoid bringing source code information into production.
After uploading sourcemap, proactively throw test errors to verify that the Error Tracking module correctly maps to source code.

Frequently asked questions

  • Confirm that sourcemap was successfully uploaded and minified-path-prefix matches the actual deployment path
  • Check that service and release-version match the application version when the error occurred
  • For WeChat Mini Programs, confirm that the sourcemap.zip for the corresponding version has been uploaded
  • Ensure sourcemap files are only uploaded to the Flashduty server, not directly exposed on the public network
  • In production, remove direct access to sourcemap files (for example, through Nginx configuration)
  • Check if API Key is valid
  • Ensure network connection is normal and CLI version is the latest
Yes. Older SDKs pack the Mini Program stack into the message field. Flashduty recognizes the stack inside the message and uses it for both SourceMap restoration and error grouping. After upgrading to a newer SDK, pre-existing errors may regroup under the new rule and the grouping may differ from what was seen before the upgrade.

Next steps

Error Grouping

Learn about error grouping mechanisms

Issue Status

Manage Issue status transitions