Troubleshooting issues with local builds

This guide topic provides help for identifying the cause of issues that may arise when building client-side applications using the ArcGIS Maps SDK for JavaScript with ES modules. Follow the recommendations and steps outlined below to effectively troubleshoot and resolve these issues.

If you encounter an issue with the SDK in a vanilla JavaScript application, without the use of a framework or bundler, it is recommended to report the issue directly to Esri Technical Support. They have the expertise to assist you in troubleshooting and resolving the issue.

Five triage steps

For issues that only occur when building applications locally on your computer, there are a few steps you can take to help isolate the cause:

Step 1 - Check for error messages. Look for any error messages or warnings in the terminal window when building the application, and in the browser's console when running the application. These messages provide important clues about where the problem is occurring, such as whether or not it is originating from inside an SDK module. Also, take note of when the error happens, such as during the build process or when the application is running, and you click on the map.

Step 2 - Search for existing issues. Before reporting a new issue, it's a good idea to search for existing issues on the Esri Community site or on the internet. Someone else may have already encountered and resolved a similar problem. Also, consider reviewing the SDK release notes for breaking changes and bug fixes and enhancements.

Step 3 - Check the documentation. Make sure you are using the SDK's API reference to verify that you are using the API correctly. You may have missed a step or misconfigured something, such as a property or method.

Step 4 - Verify the project configuration. Compare your project configuration to the sample applications on the jsapi-resources GitHub repository. The samples can offer hints and suggestions on best practices. For example, there are examples of importing CSS and setting up TypeScript.

Step 5 - Update dependencies. Where possible, ensure that you have the latest version of the SDK and any other npm package dependencies being used in the project. Outdated dependencies can sometimes cause compatibility issues. Also, upgrading to the latest version of the SDK can frequently resolve functionality issues.

Minimal reproducible application

When posting questions to the Esri Community Site, Esri GitHub repositories, or when contacting technical support, it is always recommended to provide a simple, focused sample application. Code snippets and screenshots of code often do not provide enough information to understand and diagnose issues. Sample applications help others rapidly reproduce your issue in a consistent way, and enables them to provide more targeted assistance. Here are some tips:

Tip 1 - Keep it small. Remove any unnecessary code or dependencies from your application. Focus on isolating the specific issue you are facing. This approach also lets you experiment by adding and removing functionality that may not be relevant or could interfere with solving the problem.

Tip 2 - Use a starter app. It is recommended to use the ES module samples in the jsapi-resources GitHub repository as a starting point. These samples use the @arcgis/corenpm package with minimal code, are validated weekly against next builds, and minimize the number of npm package dependencies and configuration settings.

Tip 3 - Share your app. Popular options for publicly sharing samples include codepen.io, github.com, codesandbox.io and StackBlitz. Once you create an application using these sites, you can include a link when creating a Community Post.

Understand the cause of an issue

Since local build systems consist of many different parts, determining where the problem is occurring is critical. Typically, problems occur in four areas: configuration, framework, module bundler, or the Maps SDK.

Configuration issues

The most common troubleshooting issues are related to project configuration. Most of these issues look like bugs, but typically they are not. Configuration issues occur in a number of different places, such as:

• Module bundler - e.g. webpack, rollup or esbuild configuration
• Framework - e.g. React or Angular configuration
• package.json - e.g. peer dependencies
• Maps SDK - e.g. esriConfig, OAuth tokens, API keys

Here are some common examples.

Problem 1 - Many 404 errors indicating a missing file in production builds. Developer builds work okay.

• Solution - Check the framework or module bundler documentation on setting the base path for production builds.

Problem 2 - Module parse failed: unexpected token. You may need an appropriate loader to handle this file type.

• Solution - These errors are typically related to transpiling. You may be missing a transpiler plugin or need to upgrade to a newer version of the module bundler.

Problem 3 - Error loading .wasm or .woff files.

• Solution - Configure your web server to recognize the SDK's MIME types. See the Install and setup guide topic.

Framework/bundler issues

Frameworks and bundlers have their own bugs, and these need to be researched and reported in their respective github repositories. Doing an internet search on the error message is often the fastest way to narrow down these issues and they will have to be resolved in the framework or module bundler. The errors for these bugs often mention the framework or bundler in the message. Here are a variety of examples including runtime and build errors:

React runtime error: Uncaught Error: A React form was unexpectedly submitted...

React runtime error: proxyConsole.js:64 Warning: Invalid value for prop 'cancel' on <input> tag. Either remove it from the element, or pass a string or number value to keep it in the DOM. For details, see https://reactjs.org/link/attribute-behavior

Angular build error: Error: Module build failed (from ./node_modules/@ngtools/webpack/src/ivy/index.js): ...Unknown string like token s missing from the TypeScript compilation.

Angular build error: Module parse failed: Unxpected token [5:1202]...You may need an additional loader to handle the results of these loaders

Rollup build error: [!] RollupError: Could not resolve "./b.js" from "../package1/src/a.ts"

Rollup build error: RollupError: Unexpected token...

Maps SDK issues

It's rare to encounter a Maps SDK issue that only happens with local builds. Look for errors that occur within SDK modules and error messages that appear to be related to mapping functionality. To help help isolate issues, you can also use the ESM CDN. This lets you validate SDK coding patterns without including other project dependencies and build tools. Here are some example errors:

TypeScript error: Argument of type '{ size: string; color: string; outline: { color: string; width: string; }; }' is not assignable to parameter of type 'SimpleLineSymbolProperties'.

Angular error: ERROR: ReferenceError: Cannot access lexical declaration 'e' before initialization at c._renderLegendForElement