angular/components · error

MarkerClusterer class not found, cannot construct a marker c

Error message

MarkerClusterer class not found, cannot construct a marker cluster. Please install the MarkerClusterer library: https://github.com/googlemaps/js-markerclusterer

What it means

MapMarkerClusterer lazily loads the @googlemaps/markerclusterer library and throws this error if the MarkerClusterer class is still unavailable when it tries to build the cluster. This usually means the optional peer package isn't installed or its import resolved to undefined. Unlike the other guards, this is about a missing dependency, not timing.

Source

Thrown at src/google-maps/map-marker-clusterer/map-marker-clusterer.ts:129

  async ngOnChanges(changes: SimpleChanges<this>) {
    const change = changes['renderer'] || changes['algorithm'];

    // Since the options are set in the constructor, we have to recreate the cluster if they change.
    if (this.markerClusterer && change && !change.isFirstChange()) {
      await this._createCluster();
    }
  }

  ngOnDestroy() {
    this._markersSubscription.unsubscribe();
    this._closestMapEventManager.destroy();
    this._destroyCluster();
  }

  private async _createCluster() {
    if (!markerClusterer?.MarkerClusterer && (typeof ngDevMode === 'undefined' || ngDevMode)) {
      throw Error(
        'MarkerClusterer class not found, cannot construct a marker cluster. ' +
          'Please install the MarkerClusterer library: ' +
          'https://github.com/googlemaps/js-markerclusterer',
      );
    }

    const map = await this._googleMap._resolveMap();
    this._destroyCluster();

    // Create the object outside the zone so its events don't trigger change detection.
    // We'll bring it back in inside the `MapEventManager` only for the events that the
    // user has subscribed to.
    this._ngZone.runOutsideAngular(() => {
      this.markerClusterer = new markerClusterer.MarkerClusterer({
        map,
        renderer: this.renderer,
        algorithm: this.algorithm,
        onClusterClick: (event, cluster, map) => {

View on GitHub (pinned to 0411926e7d)

Solutions

1. Install the correct library: npm install @googlemaps/markerclusterer (the one at github.com/googlemaps/js-markerclusterer).
2. Import as documented: the component loads markerClusterer lazily; if importing manually ensure 'import * as markerClusterer from @googlemaps/markerclusterer' shape matches, and rebuild.
3. Remove conflicting packages (markerclustererplus, @google/markerclusterer) that shadow or break resolution.
4. Check bundler config (Angular builder defaults are fine; custom webpack may need to include the dynamic import).
5. Verify the installed version is compatible with @angular/google-maps (markerclusterer >= 2.x).

Example fix

// before
npm install markerclustererplus
// after
npm install @googlemaps/markerclusterer

// at build time / app init
import * as mc from '@googlemaps/markerclusterer';
if (!mc?.MarkerClusterer) {
  throw new Error('@googlemaps/markerclusterer is required for <map-marker-clusterer>');
}

function hasMarkerClusterer(lib: typeof import('@googlemaps/markerclusterer') | undefined)
  : lib is typeof import('@googlemaps/markerclusterer') & { MarkerClusterer: unknown } {
  return !!lib?.MarkerClusterer;
}

try {
  await clustererInstance._createCluster();
} catch (e) {
  if ((e as Error).message.includes('MarkerClusterer class not found')) {
    console.error('Install @googlemaps/markerclusterer');
  } else { throw e; }
}

When it happens

Trigger: ngOnInit or ngOnChanges triggers _createCluster while markerClusterer?.MarkerClusterer is falsy — i.e. the markerclusterer package is not installed, was not bundled (wrong import path/version, e.g. old 'markerclustererplus' or @google/markerclusterer), or a broken lazy import returned undefined.

Common situations: Forgetting to install @googlemaps/markerclusterer, installing a similarly named but different package (MarkerClustererPlus, google.maps.MarkerClusterer v1), version mismatch where the default export shape changed, tree-shaking/bundler config dropping the lazy chunk, or ngDevMode disabled so the error is skipped but the cluster silently fails.

Related errors

• MarkerClusterer class not found, cannot construct a marker c
• Namespace google not found, cannot construct embedded google
• Cannot interact with a MarkerClusterer before it has been in
• Maps event target that uses native events must have `addEven
• Specified anchor does not implement the `getAnchor` method.

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/bc4ee635dbe61988. Report an issue: GitHub.