Get started
Reference

Troubleshooting

Troubleshooting

The problems developers hit first, each with its fix. Each package's README, in node_modules/@mountaya/<package>/README.md, has a longer list.

npm install answers 404

The @mountaya/* packages are not on npm yet. They are coming: until they are published, every install command fails this way.

Nothing appears where the map should be

The map fills its parent, and the parent has no height. Give it one: a fixed size, 100dvh, or a flex or grid track.

The map looks broken or the controls are unstyled

The stylesheet is missing. Import @mountaya/elements-react/styles.css once, at your app's entry point, or @mountaya/elements/styles.css without React.

import "@mountaya/elements-react/styles.css";

The map stays empty, and nothing is thrown

The API refused one of the map's own requests. Pass onAccessRequired and onError to MapView, or listen to accessrequired and error on MountayaMap, to see the status and the address.

<MapView
  client={client}
  onAccessRequired={({ status, url }) => console.warn(`${status} on ${url}`)}
  onError={(error) => console.error(error)}
/>;

A 402 means your agreement lacks the Tile API. A 403 means the key lacks the tiles scope.

Every control stays disabled

No map reaches the controls. Place them inside MapView, or pass the map onReady returns to MountayaElementsProvider. See Install.

A call fails with MountayaConfigurationError before any request

The client refused a call your credential cannot make. Most often it needs a session token: every Data API call does. Mint one on your server, as authentication in the SDK shows.

A 401 after a few minutes

The session token expired: it lasts five minutes. Pass a SessionTokenEngine as sessionToken, or useSessionToken's session in React, so the client mints a fresh one in time.

A 401 on every write

The token was minted without user_id, so it acts as nobody and cannot write. Mint it for the member your sign-in vouches for. See act as a member.

A 402 although the key has the scope

Your organization's agreement does not cover that API, or the Data API has no payment method on file. Enabling a scope does not lift it: talk to us, or add a card in your billing settings.

A Server Component cannot call itineraryQueryOptions

Every function in @mountaya/client-react is marked "use client". Import it from @mountaya/client-react/query instead. See server rendering.

A build cannot resolve maplibre-gl or terra-draw

These are optional packages that npm does not install for you. Add maplibre-gl@6.16.0 for any map, and terra-draw, terra-draw-maplibre-gl-adapter and @maplibre/maplibre-gl-directions for the editor.

npm install fails with ERESOLVE

Two @mountaya/* packages are at different versions. Install every @mountaya/* package at the same version.

Every known problem, by package

Use Copy for LLM on this page to hand your coding agent every entry from the six package READMEs.

Next steps

Last updated