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
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, 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 @flashcloud/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 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, mapping files, dSYMs), including path, service name, version, size, and upload time
Version Management	Manage different application versions separately through `service` and `release-version` parameters
Permission Control	Ensure only authorized users can upload or manage through `API Key`

View Source Code in Error Tracking

RUM integrates sourcemap functionality, supporting direct viewing of original source code in the Error Tracking module for precise problem localization.

Capture Frontend Errors

RUM SDK automatically captures frontend errors (such as JavaScript exceptions, Promise rejections, network errors, etc.) and sends error stack information to the server.

throw new Error("Something went wrong");

Associate SourceMap

When the file path and line number in the error stack match an uploaded sourcemap, Flashduty automatically maps the minified code error location 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

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 sourcemap upload 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

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

Next Steps

Error Grouping

Learn about error grouping mechanisms

Issue Status

Manage Issue status transitions

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 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

​Why Do You Need Source Mapping?

Map Minified Code

Precise Error Location

Improve Debugging Efficiency

​Generate SourceMap

​Upload 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 Android Symbol Files

Upload iOS dSYM Files

Symbol File Management

View Source Code in Error Tracking

Best Practices

Frequently Asked Questions

Next Steps