Troubleshooting issues with local builds

Building applications locally involves understanding many interrelated pieces including frameworks, module bundlers, transpilers, dependency libraries and the ArcGIS Maps SDK for JavaScript. This guide topic provides guidance for narrowing down the potential sources for issues.

Four triage steps

There are four basic steps for isolating problems.

Step 1 - Review. Open the browser's developer console and examine the entire error message. Most of the time there are clues in the error that will help solve the problem. Take note of when the error happens. Some errors only occur during the build process; others may only show up when you run the app in the browser or only when the app is deployed to the production environment. This information gives important hints on where the problem is occurring.

Step 2 - Search. Search for the error message on the Esri Community site or the internet. This is often the fastest and easiest way to look for answers or get hints on how to solve a problem. Also, consider reviewing the SDK release notes for breaking changes and bug fixes and enhancements.

Step 3 - Reproduce. Try to reproduce the issue in a simple, vanilla JavaScript app to help determine whether or not the issue is related to the JS Maps SDK. The ES module samples in the jsapi-resources GitHub repository are also an excellent starting point. Those samples minimize the number of dependencies. Sometimes, in the process of trying to reproduce the error you will solve the issue.

Step 4 - Provide a sample. Always provide a simple sample when posting your question to the Esri Community Site. A working sample is essential to allow others to reproduce your issue quickly. Great online options for sharing samples include codepen.io, github.com, codesandbox or StackBlitz. Code snippets do not provide enough information about a project because they don't include information on project configuration settings, dependencies or coding patterns.

Understand the cause of an issue

With the many different parts that make up local build systems, determining where the problem is occurring is critical. Typically, problems occur in three categories: configuration, framework/module bundler, or the Maps SDK.

Configuration issues

The most common errors are related to project configuration. Most of these issues look like bugs, but they are not. Here are typical areas where they occur:

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

Here are some examples of common configuration issues.

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 with the correct MIME types. See the Install and setup guide topic.

Framework/bundler issues

Frameworks and bundlers have their own bugs, and these need to be reported or researched 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 error messages for these bugs may often mention the framework or bundler. 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

First, follow the steps and recommendations above. If that hasn't resolved the issue, then try to reproduce the problem in a simple, vanilla JavaScript application, without a framework, module bundler or transpiling. Maps SDK bugs should be reported to Esri Tech Support. If the bug can only be reproduced with a framework or module bundler, then post your issue on the Esri Community site and always provide a reference to a simple GitHub repository or a link to a working StackBlitz or CodeSandbox example.

Here are some examples:

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

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.