Cannot interact with a MarkerClusterer before it has been in

Error message

Cannot interact with a MarkerClusterer before it has been initialized. Please wait for the MarkerClusterer to load before trying to interact with it.

What it means

The second half of the same guard: thrown when the Google Map exists but the MarkerClusterer instance itself has not been constructed yet (the async _createCluster hasn't finished or failed). The library refuses marker-change watching until the cluster exists so marker operations don't hit an undefined clusterer.

Source

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

    // See: https://github.com/googlemaps/js-markerclusterer/blob/main/src/markerclusterer.ts#L205
    this.markerClusterer?.onRemove();
    this.markerClusterer = undefined;
  }

  private _getInternalMarkers(markers: MarkerDirective[]): Promise<Marker[]> {
    return Promise.all(markers.map(marker => marker._resolveMarker()));
  }

  private _assertInitialized(): asserts this is {markerClusterer: MarkerClusterer} {
    if (typeof ngDevMode === 'undefined' || ngDevMode) {
      if (!this._googleMap.googleMap) {
        throw Error(
          'Cannot access Google Map information before the API has been initialized. ' +
            'Please wait for the API to load before trying to interact with it.',
        );
      }
      if (!this.markerClusterer) {
        throw Error(
          'Cannot interact with a MarkerClusterer before it has been initialized. ' +
            'Please wait for the MarkerClusterer to load before trying to interact with it.',
        );
      }
    }
  }
}

View on GitHub (pinned to 0411926e7d)

Solutions

Fix any prior _createCluster failure first (install @googlemaps/markerclusterer) — this error often follows error 174.
Delay marker rendering until after the clusterer signals readiness (e.g. ngAfterViewInit + small delay or a loaded flag).
Add markers in the clusterer's content projection after the map ready event, not in ngOnInit.
Avoid toggling the clusterer with *ngIf while markers continue emitting; keep it mounted once the map is ready.
Retry marker updates on the next change-detection cycle after initialization completes.

Example fix

// before
// markers emitted immediately; cluster not built yet -> throws
this.markers = initialMarkers; // set in same tick as clusterer mount
// after
this.map.ready.subscribe(() => {
  setTimeout(() => { this.markers = initialMarkers; });
});

Defensive patterns

Strategy: retry

Validate before calling

if (!mapRef?.googleMap || !clustererReady) { /* retry after tick */ }

Type guard

function isClusterReady(c: MarkerClusterer | undefined | null): c is MarkerClusterer { return !!c; }

Try / catch

try {
  watchMarkers();
} catch (e) {
  if ((e as Error).message.includes('MarkerClusterer before it has been initialized')) {
    setTimeout(watchMarkers, 0); // retry after async cluster creation
  } else { throw e; }
}

Prevention

Fix underlying _createCluster failures first (missing library).
Add markers after the cluster has had a chance to build (post-ready tick).
Avoid *ngIf toggling that destroys/recreates the clusterer mid-emit.
Sequence: map ready -> clusterer mounted -> markers rendered.
Keep clusterer mounted for the map's lifetime.

When it happens

Trigger: _watchForMarkerChanges runs (markers change, QueryList emits) after the map exists but before the async _createCluster resolves the cluster — e.g. adding markers in the same tick the clusterer mounts, or after _createCluster threw error 174 so markerClusterer never got set.

Common situations: Markers rendered synchronously with the clusterer at bootstrap; missing markerclusterer library (error 174) leaving the cluster undefined; rapid *ngFor updates firing before the cluster promise resolves.

Related errors

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