MatDialog Backdrop Persists and Body Scroll Stays Locked: Diagnostic Guide

The recognizable condition

A MatDialog opens normally, then appears to close but a semi-transparent backdrop remains and body scroll stays locked. Alternatively, ESC and backdrop click stop working after the first open. The problem often worsens after navigation or repeated open-close cycles and may be accompanied by console errors from the dialog content.

MatDialog uses CDK Overlay to create a cdk-overlay-container, a cdk-overlay-backdrop for the dim layer, and a cdk-overlay-pane for the dialog. Closing is supposed to remove those nodes, restore body overflow, release the focus trap, and complete the afterClosed observable.

Cause diagnostic table

Ordered checks

1. Confirm single open per action and store the ref. In the component that triggers the dialog, ensure you keep a reference to MatDialogRef and avoid opening again while it is open. Check the call site for repeated subscriptions or click handlers.
2. Verify afterClosed completes and close is called on all paths. Subscribe to dialogRef.afterClosed and log completion. Ensure dialogRef.close is invoked before navigation, form submit, or error handling. Look for early returns that skip close.
3. Inspect DOM for orphaned overlay nodes. Open browser devtools Elements panel after the dialog should be closed. Count elements with class cdk-overlay-backdrop and cdk-overlay-pane. Run in console as user with no special permissions:

   document.querySelectorAll('.cdk-overlay-backdrop').length

   Expected check: zero after close. Risk: do not manually remove nodes; Angular Material manages lifecycle and manual removal leaves internal state inconsistent.
4. Check console for errors in dialog content. Errors thrown in ngOnInit, ngAfterViewInit, or async pipes inside the dialog can prevent teardown. Look for uncaught exceptions at the time of close.
5. Validate MatDialogModule import scope. MatDialogModule should be imported once at a shared root or in the feature module that hosts the dialog. Search the codebase for multiple imports, especially in lazy loaded modules. Duplicate imports can create separate overlay containers.
6. Review overlayContainer configuration. If a custom overlayContainer element is provided via providers, verify the element exists for the app lifetime and is not removed by *ngIf or route change.

Fixes tied to findings

Duplicate opens and lost refs

Guard the open call and reuse the existing ref. Close the previous dialog before opening a new one. Ensure afterClosed subscription is completed and not re-subscribed on each click.

Unhandled error blocks close

Wrap dialog content in an error boundary or try-catch around async operations. Ensure dialogRef.close is called in finally blocks. Avoid setting disableClose globally; it masks root causes and changes expected user behavior.

Duplicate MatDialogModule imports

Remove duplicate MatDialogModule imports from lazy modules. Use a single import at root or in a shared module imported once. Verify only one cdk-overlay-container exists in the DOM after app bootstrap.

Custom overlayContainer removed

Restore the default overlay container or provide a stable custom container element that remains in the DOM for the app lifetime. Removing the container causes orphaned backdrops.

Focus trap anomalies

Avoid disabling focus trap via custom overlay config. Test focus order inside the dialog and confirm focus returns to the trigger element on close. Overlay scroll strategy and focus trap behavior are version sensitive.

Verification

• Open a minimal dialog with static content and verify backdrop removal and body scroll restoration after close.
• Log dialogRef.afterClosed completion and count cdk-overlay-backdrop elements before and after close to detect orphans.
• Test repeated open-close cycles and navigation away while dialog is open to confirm no lingering overlay state.
• Use browser devtools to inspect focus order inside the dialog and confirm focus is trapped and returned to the trigger element on close.

Escalation criteria

Escalate if the backdrop persists across route changes and survives a full application reload, if memory usage grows with each open indicating overlay leaks, or if focus trap violations are reported by accessibility audits and cannot be reproduced with a minimal dialog. These suggest framework-level overlay container corruption requiring version-specific investigation.

Limitations: behavior of overlay scroll strategy and focus trap varies by Angular Material version. Assumptions from older releases may not apply to newer releases. Current verification is required for your specific version and build.