Cannot access Google Map information before the API has been

Error message

Cannot access Google Map information before the API has been initialized. Please wait for the API to load before trying to interact with it.

What it means

Thrown by MapMarkerClusterer's _assertInitialized when the underlying Google Map instance (this._googleMap.googleMap) is still undefined. The clusterer needs a live map to attach to; this guard reports that the Maps API/map hasn't initialized yet instead of failing obscurely later. It is dev-mode (ngDevMode) gated.

Source

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

    );
  }

  private _destroyCluster() {
    // TODO(crisbeto): the naming here seems odd, but the `MarkerCluster` method isn't
    // exposed. All this method seems to do at the time of writing is to call into `reset`.
    // 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

Render the marker clusterer only after the map is ready: wrap in @ngIf driven by map.ready subscription or a loaded flag.
Ensure the clusterer is inside/attached to a MapComponent whose googleMap is set.
Verify the Google Maps JS API script loads (network tab, API key validity, billing enabled).
Defer marker addition until ngAfterViewInit + map ready instead of ngOnInit.
Catch the error as a signal to retry initialization once the map loads.

Example fix

// before
<google-map #map><map-marker-clusterer [map]="map.googleMap">...</map-marker-clusterer></google-map>
// after
<google-map #map (mapReady)="mapLoaded = true">
  <ng-container *ngIf="mapLoaded">
    <map-marker-clusterer [map]="map.googleMap">...</map-marker-clusterer>
  </ng-container>
</google-map>

Defensive patterns

Strategy: validation

Validate before calling

if (!mapRef?.googleMap) { /* wait for map ready before mounting clusterer */ }

Type guard

function isMapReady(map: google.maps.Map | undefined | null): map is google.maps.Map { return !!map; }

Try / catch

try {
  clusterer.getMarkers();
} catch (e) {
  if ((e as Error).message.includes('before the API has been initialized')) {
    map.ready.subscribe(() => retry());
  } else { throw e; }
}

Prevention

Render clusterer only after map.ready fires.
Always pass [map]="map.googleMap" from a mounted MapComponent.
Validate API key/script load first.
Defer marker setup to ngAfterViewInit.
Watch network tab for failed Maps API loads.

When it happens

Trigger: _watchForMarkerChanges calls _assertInitialized while _googleMap.googleMap is undefined — e.g. the clusterer renders before the MapComponent has created its map (API script not loaded yet, or clusterer placed outside a <google-map> reference that has not initialized).

Common situations: Adding markers immediately at app bootstrap before the map script loads, using the clusterer without a proper MapComponent parent/reference, slow network delaying the Maps API, or map input not yet bound.

Related errors

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