Troubleshooting source map uploads

Fix common issues when uploading source maps to Grafana Cloud and verify that uploads work correctly.

Verify uploads work correctly

To confirm source map uploads are working properly, complete these verification steps:

Check bundler plugin output - Verify the bundler plugin generated source maps by checking build output. Enable verbose logging for detailed information. Refer to bundlers for configuration details.
Confirm files reached Grafana Cloud - Open Frontend Observability and navigate to your app > Settings > Source Maps to see uploaded files.
Test error trace mapping - View an error trace to validate proper deobfuscation. Error traces should display original file names and line numbers instead of minified references.

Common issues and solutions

Configuration problems

Wrong endpoint - The source map upload endpoint differs from the Faro Collector endpoint. Use the endpoint from Frontend Observability > Settings > Source Maps > Configure source map uploads.

Missing API key permissions - Ensure your API key has these scopes: sourcemaps:read, sourcemaps:write, and sourcemaps:delete.

Region mismatch - Upload to the same Grafana Cloud region where your stack resides.

Bundle ID issues

Missing bundle ID - Confirm the bundle ID exists in your application’s window object. Look for: window.["__faroBundleId_<appName>"]

Bundle ID mismatch - Error stacks reference a bundle ID that doesn’t match uploaded files. Set a consistent bundle ID during builds or read from environment variables when uploading.

Uploads succeed but aren’t visible - Verify you’re viewing the correct app, time range, and bundle ID filter in the UI.

Build and file issues

No source maps generated - Confirm production builds create .map files and they aren’t removed by build tools.

Files exceed 30MB - Reduce source map size by using sourceMap: 'hidden' instead of inline maps, excluding vendor code, or splitting bundles. The 30MB limit applies to uncompressed files even when using gzip.

Next.js path problems - If both server and client bundles exist, set nextjs: true in the Webpack plugin to prepend _next/ paths.

Server-side rendering conflicts - Bundler plugins support client-side bundles only. Server-side rendering isn’t supported.

Debug upload issues

To get detailed information about upload attempts:

Enable verbose logging - Set verbose: true in bundler plugins or use --verbose with the CLI to see detailed request information.
Check upload status - Open Frontend Observability and navigate to your app > Settings > Source Maps to view received files and upload history.