MarkerClusterer class not found, cannot construct a marker c

Error message

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

What it means

DeprecatedMapMarkerClusterer wraps the external MarkerClustererPlus library. In ngOnInit, once the Google Map resolves, the component checks that a global MarkerClusterer constructor exists; if the library was never loaded, it cannot construct the cluster and throws. This is a missing-dependency error, not an Angular bug.

Source

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

   * See
   * googlemaps.github.io/v3-utility-library/classes/
   * _google_markerclustererplus.markerclusterer.html
   */
  markerClusterer?: MarkerClustererInstance;

  /** Event emitted when the clusterer is initialized. */
  @Output() readonly markerClustererInitialized: EventEmitter<MarkerClustererInstance> =
    new EventEmitter<MarkerClustererInstance>();

  ngOnInit() {
    if (this._canInitialize) {
      this._ngZone.runOutsideAngular(() => {
        this._googleMap._resolveMap().then(map => {
          if (
            typeof MarkerClusterer !== 'function' &&
            (typeof ngDevMode === 'undefined' || ngDevMode)
          ) {
            throw Error(
              'MarkerClusterer class not found, cannot construct a marker cluster. ' +
                'Please install the MarkerClustererPlus library: ' +
                'https://github.com/googlemaps/js-markerclustererplus',
            );
          }

          // 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.markerClusterer = this._ngZone.runOutsideAngular(() => {
            return new MarkerClusterer(map, [], this._combineOptions());
          });

          this._assertInitialized();
          this._eventManager.setTarget(this.markerClusterer);
          this.markerClustererInitialized.emit(this.markerClusterer);
        });
      });

View on GitHub (pinned to 0411926e7d)

Solutions

Install MarkerClustererPlus: npm install @googlemaps/markerclustererplus and import it so the global is defined.
Or add the library's script tag before the app bootstraps.
Prefer migrating to the non-deprecated @googlemaps/markerclusterer package with MapAdvancedMarker.
If lazy-loading, ensure the script resolves before the cluster component's ngOnInit.

Example fix

// before
import 'google-maps'; // MarkerClustererPlus never imported
// after
import 'google-maps';
import '@googlemaps/markerclustererplus/dist/markerclustererplus.min.js'; // or npm package import

Defensive patterns

Strategy: validation

Validate before calling

if (typeof (window as any).MarkerClusterer !== 'function') {
  throw new Error('MarkerClustererPlus not loaded: npm i @googlemaps/markerclustererplus and import it before rendering <map-marker-clusterer>.');
}

Type guard

function hasMarkerClusterer(w: Window): w is Window & {MarkerClusterer: Function} {
  return typeof (w as any).MarkerClusterer === 'function';
}

Try / catch

try {
  await clusterComponent._resolveMap();
} catch (e) {
  if (String((e as Error).message).includes('MarkerClusterer')) {
    await loadScript('https://cdn.jsdelivr.net/npm/@googlemaps/markerclustererplus');
  }
}

Prevention

Import the MarkerClustererPlus package at app startup before any map components render.
Prefer the modern @googlemaps/markerclusterer package over the deprecated wrapper.
Verify globals exist in a CI smoke test that renders the map once.
If lazy-loading the script, sequence it before component initialization.

When it happens

Trigger: Rendering <map-marker-clusterer> in the browser when window.MarkerClusterer is undefined because MarkerClustererPlus was never imported or loaded before the map resolves.

Common situations: Forgetting to add the js-markerclustererplus package or its <script> tag; loading the clustering script lazily after Angular initializes; SSR/browser platform checks where script injection failed; upgrading google-maps components without migrating to @googlemaps/markerclusterer.

Related errors

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