Source Mapping and Error Tracking

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 via Flashduty CLI
WeChat Mini Program: Upload the sourcemap.zip generated by miniprogram-ci get-dev-source-map via Flashduty CLI
Android: Automatically upload ProGuard/R8 mapping files and NDK symbol files via a Gradle plugin
iOS: Upload dSYM symbol files via Flashduty CLI

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.

Why Do You Need Source Mapping?

In modern application development, code is typically minified, obfuscated, or compiled to optimize loading speed and performance. Whether it’s JavaScript minification on the Web, WeChat Mini Program package transformation, ProGuard/R8 obfuscation on Android, or compilation optimization on iOS, these processes cause code location information in error stacks to not directly map to the original source code, increasing debugging difficulty.

Map Minified Code

SourceMap records the mapping relationship between minified code and original code, allowing developers to view unminified source code during debugging

Precise Error Location

Through SourceMap, you can directly locate the specific position in the original source code in error tracking

Improve Debugging Efficiency

Developers don’t need to manually decode minified files, saving time troubleshooting issues

Generate SourceMap

Most modern build tools (such as Webpack, Rollup, or Vite) support generating SourceMap.

Webpack
Vite
Rollup

Enable SourceMap generation in webpack.config.js:

module.exports = {
  mode: "production",
  devtool: "source-map", // Generate separate .map files
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist"),
  },
};

After building, the dist directory will contain bundle.js and the corresponding bundle.js.map file.

Configure in vite.config.js:

export default {
  build: {
    sourcemap: true, // Generate sourcemap
  },
};

Configure in rollup.config.js:

export default {
  output: {
    sourcemap: true,
  },
};

Upload SourceMap

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

Install Flashduty CLI

Ensure Node.js is installed, then install via npm:

npm install -g @flashcatcloud/flashcat-cli

Configure Upload Parameters

In the “Application Management” - “Source Code Management” menu, click the “Upload Source Code” panel and fill in the following information:

API Key

string

required

Used to authenticate your identity

Service Name

string

required

Application service name (e.g., my-service)

Version

string

required

Application release version (e.g., 1.0.0)

Minified Path Prefix

string

required

Path prefix for minified files (e.g., /assets)

Execute Upload

Run the generated script in the project root directory:

flashcat-cli sourcemaps upload \
  --service my-service \
  --release-version 1.0.0 \
  --minified-path-prefix /assets \
  --api-key your-api-key \
  ./dist

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.

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, e.g. __FULL__/app-service.js.map
Subpackage .js.map entries are placed under a directory named after the subpackage, e.g. 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, etc.) 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.

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.

API Key

string

required

Authenticates the upload request. The page prioritizes API Keys that the current account can access.

Service Name

string

required

Mini Program service name, such as my-mp. Error parsing uses this value to match the service in error events.

Release Version

string

required

Mini Program release version, such as 1.2.3. Error parsing uses this value to match the version in error events.

SourceMap ZIP File Path

string

required

Path to the archive generated by miniprogram-ci get-dev-source-map, such as ./sourcemap.zip.

AppID

string

WeChat Mini Program appid, e.g. wxbad3e0a65782821c. Used to disambiguate uploads when multiple Mini Programs share the same service + version. Optional when only one Mini Program is involved.

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:

FLASHCAT_API_KEY=your-api-key flashcat-cli sourcemaps upload-miniprogram \
  --service my-mp \
  --release-version 1.2.3 \
  --sourcemap-zip ./sourcemap.zip \
  --appid wxbad3e0a65782821c

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.

Add Gradle Plugin

Add the Flashcat Gradle plugin to your app’s build.gradle:

// In your app's build.gradle script
plugins {
    id("cloud.flashcat.fc-sdk-android-gradle-plugin") version "1.0.0"
}

Configure API Key

Provide the API Key via environment variables or project configuration file:

# Set environment variable (choose one)
export FC_API_KEY=your-api-key
# or
export FLASHCAT_API_KEY=your-api-key

You can also create a flashcat-ci.json configuration file in the project root:

{
  "apiKey": "your-api-key"
}

API Keys can be created and managed in the console’s “API Key Management” page.

Run Upload Tasks

After building, execute Gradle tasks to upload symbol files:

# Upload ProGuard/R8 mapping file
./gradlew uploadMappingRelease

# If your project contains NDK native code, upload NDK symbol files
./gradlew uploadNdkSymbolFilesRelease

If your project uses multiple flavors, the plugin will provide upload tasks for each variant that has obfuscation enabled.

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.

Install Flashduty CLI

Ensure Node.js is installed, then install via npm:

npm install -g @flashcatcloud/flashcat-cli

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)

Execute Upload

Upload dSYM files using Flashduty CLI:

FLASHCAT_API_KEY=your-api-key flashcat-cli dsyms upload ./app.dSYM

You can also fill in parameters in the “Source Code Management” panel in the console to automatically generate the upload command.

Symbol File Management

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

Feature	Description
View Uploaded Symbol Files	List all uploaded files (SourceMaps, Mini Program SourceMaps, mapping files, dSYMs), including path, service name, version, size, and upload time
Filter by Platform	Switch between Web, WeChat Mini Program, iOS, and Android tabs to view symbol files for each platform
Version Management	Manage different application versions separately through `service` and `release-version` parameters
Mini Program Dimensions	The WeChat Mini Program list shows the AppID column (from `metadata.appid`) and the Subpackage column (from `metadata.subpackage`); the main package without a subpackage tag shows “Main Package”, and an unspecified AppID shows `-`
Permission Control	Ensure only authorized users can upload or manage through `API Key`

View Source Code in Error Tracking

RUM Error Tracking can use Web sourcemap files, WeChat Mini Program SourceMaps, Android mapping files, and iOS dSYM files to restore error stacks and show original source code locations in error details for precise debugging.

Capture Errors

RUM SDK automatically captures application errors and sends error stack information to the server. Web scenarios typically include JavaScript exceptions, Promise rejections, and network errors; native scenarios include crashes, exceptions, and stack information required for symbolication.

throw new Error("Something went wrong");

Associate Symbol Files

When file paths, line numbers, or address information in the error stack match uploaded Web sourcemap files, WeChat Mini Program SourceMaps, Android mapping files, or iOS dSYM files, Flashduty automatically maps minified, obfuscated, or compiled error locations back to the original source code.Minified file stack:

Error: Something went wrong
    at Object.<anonymous> (/assets/index-5e0391ac.js:1:123)

Mapped source code:

Error: Something went wrong
    at App.render (src/components/App.js:45:10)

View Error Details

In the Error Tracking module, click a specific error record to view:

Error message: e.g., 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

If a Mini Program error stack has not been resolved, the notice in error details links to the Mini Program type on the Source Code Management page and can open the upload panel for the corresponding version’s sourcemap.zip.

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

Standardize SourceMap Upload

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:

- name: Upload SourceMaps
  run: |
    flashcat-cli sourcemaps upload \
      --service my-service \
      --release-version ${{ github.sha }} \
      --minified-path-prefix /assets \
      --api-key ${{ secrets.FLASHCAT_API_KEY }} \
      ./dist

Version Management

Use the --release-version parameter to match the application version number for easy tracking of specific version sourcemaps.

Clean Up Source Code

Delete sourcemap files before uploading resources to CDN to avoid bringing source code information into production.

Test Mapping Effect

After uploading sourcemap, proactively throw test errors to verify that the Error Tracking module correctly maps to source code.

Frequently Asked Questions

Why isn't the error stack mapped to source code?

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

How to prevent SourceMap from leaking sensitive information?

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 (e.g., through Nginx configuration)

What if SourceMap upload fails?

Check if API Key is valid
Ensure network connection is normal and CLI version is the latest

Can Mini Program errors with empty stacks but a stack-like message still be source-mapped?

Yes. For Mini Program errors emitted by older SDKs that pack the stack into the message field, Flashduty automatically recognizes the stack inside the message and feeds it into 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.

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Source Mapping and Error Tracking

Why Do You Need Source Mapping?

Map Minified Code

Precise Error Location

Improve Debugging Efficiency

Generate SourceMap

Upload SourceMap

Upload WeChat Mini Program SourceMap

Upload Android Symbol Files

Upload iOS dSYM Files

Symbol File Management

View Source Code in Error Tracking

Best Practices

Frequently Asked Questions

Next Steps

Error Grouping

Issue Status

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Documentation Index

​Why Do You Need Source Mapping?

Map Minified Code

Precise Error Location

Improve Debugging Efficiency

​Generate SourceMap

​Upload SourceMap

​Upload WeChat Mini Program SourceMap

​Upload Android Symbol Files

​Upload iOS dSYM Files

​Symbol File Management

​View Source Code in Error Tracking

​Best Practices

​Frequently Asked Questions

​Next Steps

Error Grouping

Issue Status

Why Do You Need Source Mapping?

Generate SourceMap

Upload SourceMap

Upload WeChat Mini Program SourceMap

Upload Android Symbol Files

Upload iOS dSYM Files

Symbol File Management

View Source Code in Error Tracking

Best Practices

Frequently Asked Questions

Next Steps