Cannot interact with a Google Map KmlLayer before it has bee

Error message

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

What it means

Thrown by MapKmlLayer's dev-mode assertion when its internal google.maps.KmlLayer is still undefined. The layer is constructed asynchronously after the map and layer inputs are ready. The guard ensures early interaction produces an actionable error instead of an undefined-object TypeError.

Source

Thrown at src/google-maps/map-kml-layer/map-kml-layer.ts:204

        this._assertInitialized();
        this.kmlLayer.setOptions(options);
      }
    });
  }

  private _watchForUrlChanges() {
    this._url.pipe(takeUntil(this._destroyed)).subscribe(url => {
      if (url && this.kmlLayer) {
        this._assertInitialized();
        this.kmlLayer.setUrl(url);
      }
    });
  }

  private _assertInitialized(): asserts this is {kmlLayer: google.maps.KmlLayer} {
    if (typeof ngDevMode === 'undefined' || ngDevMode) {
      if (!this.kmlLayer) {
        throw Error(
          'Cannot interact with a Google Map KmlLayer before it has been ' +
            'initialized. Please wait for the KmlLayer to load before trying to interact with it.',
        );
      }
    }
  }
}

View on GitHub (pinned to 0411926e7d)

Solutions

Defer accessor calls until after view init or map ready (MapComponent.ready subscription).
Poll/await layer status only after initialization completes; use ngAfterViewInit or a ready flag.
Verify the Google Maps script loads successfully (check network/console for script errors).
Ensure the KML layer component is inside a MapComponent so it receives the map and initializes.
Wrap accessor calls in try-catch as a dev-time safety net.

Example fix

// before
const status = this.kmlLayer.getStatus(); // throws too early
// after
this.map.ready.subscribe(() => {
  const status = this.kmlLayer.getStatus();
});

Defensive patterns

Strategy: validation

Validate before calling

if (!kmlLayerRef) { /* defer status polling */ }

Type guard

function isKmlLayerReady(l: MapKmlLayer | undefined): l is MapKmlLayer { return !!l; }

Try / catch

try {
  const status = kmlLayer.getStatus();
} catch (e) {
  if ((e as Error).message.includes('KmlLayer')) {
    // retry after map ready
  } else { throw e; }
}

Prevention

Start status polling only after ngAfterViewInit/map ready.
Keep layer inside the map component template.
Verify API script loads before mounting layers.
Don't poll in ngOnInit.
Guard stale references after *ngIf re-creation.

When it happens

Trigger: Calling getDefaultViewport(), getMetadata(), getStatus(), getUrl(), getZIndex(), or initializing paths that run before kmlLayer is created — e.g. calling these in ngOnInit, before the map is ready, or before the Google Maps API loads.

Common situations: Reading KML layer status right after mounting, polling getStatus before initialization, conditional rendering (*ngIf) that recreates the layer while old references are used, missing API key/script so initialization never completes.

Related errors

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