You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Due for payment 2025-10-21] [$250] Track distance - No map preview when switch from offline to online mode #71764
The issue arises because the mapbox-gl library expects a valid DOM element (container) to be present at the time the map instance is created. In our case, after transitioning from offline to online, MapViewImpl is re-mounted via React.lazy in combination with an ErrorBoundary, which re-renders the component when resetKeys change. However, while React does remount the component, it does not guarantee that the DOM elements are already present or that the ref to the container has been set by the time mapbox-gl.Map is called.
Since the map is initialized synchronously during the first render of the Map component (from the react-map-gl library, which internally calls new mapboxgl.Map()), if the ref is still null or the DOM has not yet been inserted, mapbox-gl throws the error: Invalid type: 'container' must be a String or HTMLElement.
That is, the reason for the problem is that when we switch from offline to online mode, the component is rendered, but due to the use of a lazy container, it is still null, which causes an error, and even when the container appears, it is no longer re-rendered because we have an error.
What changes do you think we should make in order to solve the problem?
We should recreate map when coming from offline:
Here is solutions:
What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?
N/A
What alternative solutions did you explore? (Optional)
Reminder: Please use plain English, be brief and avoid jargon. Feel free to use images, charts or pseudo-code if necessary. Do not post large multi-line diffs or write walls of text. Do not create PRs unless you have been hired for this job.
changed the title [-]Track distance - No map preview when switch from offline to online mode[/-][+][$250] Track distance - No map preview when switch from offline to online mode[/+]on Oct 3, 2025
React.lazy Anti-Pattern: Declaring React.lazy() inside a component with useMemo violates React's recommended
usage. According to https://react.dev/reference/react/lazy, lazy components should be declared at the module
level, not inside components.
Component Identity Issues: When useMemo recreates the lazy component (even with the same dependency), React
treats it as a different component type, causing unmounting/remounting issues that break the map initialization.
Mapbox Container Timing: The mapbox-gl library requires a valid DOM container at initialization. When the lazy
component is recreated and remounted during offline→online transition, there's a race condition:
- ErrorBoundary resets when coming online
- MapViewImpl is recreated by useMemo
- React attempts to render but the ref container may be null
- Mapbox throws: Invalid type: 'container' must be a String or HTMLElement
- Error state prevents re-render even when container becomes available
Missing Network State Dependency: The useMemo dependency array doesn't include isOffline, so when network
status changes, the component doesn't properly reset to handle the new online state.
What changes do you think we should make in order to solve the problem?
Solution: Move lazy declaration to module level and add proper remount keys
App/src/components/MapView/MapView.website.tsx:
Move React.lazy() outside component (Line 11-12):
// Before (incorrect - inside component with useMemo):
function MapView({ref, ...props}: MapViewProps) {
const MapViewImpl = useMemo(
() => lazy(() => import('./MapViewImpl.website')),
[errorResetKey],
);
// ...
}
// After (correct - at module level):
import React, {lazy, Suspense, useEffect, useState} from 'react';
// ... other imports
// Declare lazy component outside component cycle as recommended by React documentation
const MapViewImpl = lazy(() => import('./MapViewImpl.website'));
function MapView({ref, ...props}: MapViewProps) {
// ... component logic
}
The solution for this issue has been 🚀 deployed to production 🚀 in version 9.2.30-6 and is now subject to a 7-day regression period 📆. Here is the list of pull requests that resolve this issue:
@FitseTLT / @ahmedGaber93@brianlee-expensify The PR fixing this issue has been merged! The following checklist (instructions) will need to be completed before the issue can be closed. Please copy/paste the BugZero Checklist from here into a new comment on this GH and complete it. If you have the K2 extension, you can simply click: [this button]
[Contributor] The offending PR has been commented on, pointing out the bug it caused and why, so the author and reviewers can learn from the mistake.
Link to comment:
[Contributor] If the regression was CRITICAL (e.g. interrupts a core flow) A discussion in #expensify-open-source has been started about whether any other steps should be taken (e.g. updating the PR review checklist) in order to catch this type of bug sooner.
Link to discussion:
[Contributor] If it was decided to create a regression test for the bug, please propose the regression test steps using the template below to ensure the same bug will not reach production again.
Regression Test Proposal Template
[BugZero Assignee] Create a GH issue for creating/updating the regression test once above steps have been agreed upon.
[Contributor] The offending PR has been commented on, pointing out the bug it caused and why, so the author and reviewers can learn from the mistake.
Link to comment: N/A. There’s no clear offending PR — the issue appears to be in the Mapbox library itself.
[Contributor] If the regression was CRITICAL (e.g. interrupts a core flow) A discussion in #expensify-open-source has been started about whether any other steps should be taken (e.g. updating the PR review checklist) in order to catch this type of bug sooner.
Link to discussion: N/A.
[Contributor] If it was decided to create a regression test for the bug, please propose the regression test steps using the template below to ensure the same bug will not reach production again.
[BugZero Assignee] Create a GH issue for creating/updating the regression test once above steps have been agreed upon.
Activity
melvin-bot commentedon Oct 2, 2025
Triggered auto assignment to @brianlee-expensify (
Bug), see https://stackoverflow.com/c/expensify/questions/14418 for more details. Please add this bug to a GH project, as outlined in the SO.Eskalifer1 commentedon Oct 2, 2025
Proposal
Please re-state the problem that we are trying to solve in this issue.
Track distance - No map preview when switch from offline to online mode
What is the root cause of that problem?
The problem lies in lazy import here:
App/src/components/MapView/MapView.website.tsx
Lines 27 to 31 in af62054
The issue arises because the mapbox-gl library expects a valid DOM element (container) to be present at the time the map instance is created. In our case, after transitioning from offline to online, MapViewImpl is re-mounted via React.lazy in combination with an ErrorBoundary, which re-renders the component when resetKeys change. However, while React does remount the component, it does not guarantee that the DOM elements are already present or that the ref to the container has been set by the time mapbox-gl.Map is called.
Since the map is initialized synchronously during the first render of the Map component (from the react-map-gl library, which internally calls new mapboxgl.Map()), if the ref is still null or the DOM has not yet been inserted, mapbox-gl throws the error: Invalid type: 'container' must be a String or HTMLElement.
That is, the reason for the problem is that when we switch from offline to online mode, the component is rendered, but due to the use of a lazy container, it is still null, which causes an error, and even when the container appears, it is no longer re-rendered because we have an error.
What changes do you think we should make in order to solve the problem?
We should recreate map when coming from offline:
Here is solutions:
What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?
N/A
What alternative solutions did you explore? (Optional)
Reminder: Please use plain English, be brief and avoid jargon. Feel free to use images, charts or pseudo-code if necessary. Do not post large multi-line diffs or write walls of text. Do not create PRs unless you have been hired for this job.
FitseTLT commentedon Oct 2, 2025
Proposal
Please re-state the problem that we are trying to solve in this issue.
Track distance - No map preview when switch from offline to online mode
What is the root cause of that problem?
We are wrongly declaring lazy inside the component here
App/src/components/MapView/MapView.website.tsx
Lines 27 to 31 in 3262b4b
which can cause unexpected state reset just like mentioned in the documentation
What changes do you think we should make in order to solve the problem?
lazy should be declared outside component cycle to avoid this kind of issue as recommeneded in the documentation
What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?
N / A
What alternative solutions did you explore? (Optional)
brianlee-expensify commentedon Oct 3, 2025
reproduced on staging.new.expensify.com - user would need to refresh in order for the map to load again
2025-10-02_17-57-59.mp4
[-]Track distance - No map preview when switch from offline to online mode[/-][+][$250] Track distance - No map preview when switch from offline to online mode[/+]melvin-bot commentedon Oct 3, 2025
Job added to Upwork: https://www.upwork.com/jobs/~021973915688319704310
melvin-bot commentedon Oct 3, 2025
Triggered auto assignment to Contributor-plus team member for initial proposal review - @ahmedGaber93 (
External)muhammad-ali-abbasi commentedon Oct 3, 2025
Please re-state the problem that we are trying to solve in this issue.
Track distance - No map preview when switch from offline to online mode
What is the root cause of that problem?
The problem lies in how the MapViewImpl lazy component is declared inside the component lifecycle:
App/src/components/MapView/MapView.website.tsx:
Root Cause Analysis:
usage. According to https://react.dev/reference/react/lazy, lazy components should be declared at the module
level, not inside components.
treats it as a different component type, causing unmounting/remounting issues that break the map initialization.
component is recreated and remounted during offline→online transition, there's a race condition:
- ErrorBoundary resets when coming online
- MapViewImpl is recreated by useMemo
- React attempts to render but the ref container may be null
- Mapbox throws: Invalid type: 'container' must be a String or HTMLElement
- Error state prevents re-render even when container becomes available
status changes, the component doesn't properly reset to handle the new online state.
What changes do you think we should make in order to solve the problem?
Solution: Move lazy declaration to module level and add proper remount keys
App/src/components/MapView/MapView.website.tsx:
}
What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?
N/A
What alternative solutions did you explore?
N/A
23 remaining items
melvin-bot commentedon Oct 14, 2025
The solution for this issue has been 🚀 deployed to production 🚀 in version 9.2.30-6 and is now subject to a 7-day regression period 📆. Here is the list of pull requests that resolve this issue:
If no regressions arise, payment will be issued on 2025-10-21. 🎊
For reference, here are some details about the assignees on this issue:
melvin-bot commentedon Oct 14, 2025
@FitseTLT / @ahmedGaber93 @brianlee-expensify The PR fixing this issue has been merged! The following checklist (instructions) will need to be completed before the issue can be closed. Please copy/paste the BugZero Checklist from here into a new comment on this GH and complete it. If you have the K2 extension, you can simply click: [this button]
brianlee-expensify commentedon Oct 21, 2025
BugZero Checklist:
[Contributor] The offending PR has been commented on, pointing out the bug it caused and why, so the author and reviewers can learn from the mistake.
Link to comment:
[Contributor] If the regression was CRITICAL (e.g. interrupts a core flow) A discussion in #expensify-open-source has been started about whether any other steps should be taken (e.g. updating the PR review checklist) in order to catch this type of bug sooner.
Link to discussion:
[Contributor] If it was decided to create a regression test for the bug, please propose the regression test steps using the template below to ensure the same bug will not reach production again.
Regression Test Proposal Template
[BugZero Assignee] Create a GH issue for creating/updating the regression test once above steps have been agreed upon.
Link to issue:
Regression Test Proposal
Precondition:
Test:
Do we agree 👍 or 👎
brianlee-expensify commentedon Oct 21, 2025
@ahmedGaber93 can you fill out the BugZero checklist above?
brianlee-expensify commentedon Oct 21, 2025
Payment Summary
Contributor: @FitseTLT paid $250 via Upwork
Contributor+: @ahmedGaber93 due $250 via NewDot
brianlee-expensify commentedon Oct 23, 2025
@ahmedGaber93 just wanted to bump here regarding the BZ checklist above!
ahmedGaber93 commentedon Oct 25, 2025
BugZero Checklist:
[Contributor] The offending PR has been commented on, pointing out the bug it caused and why, so the author and reviewers can learn from the mistake.
Link to comment: N/A. There’s no clear offending PR — the issue appears to be in the Mapbox library itself.
[Contributor] If the regression was CRITICAL (e.g. interrupts a core flow) A discussion in #expensify-open-source has been started about whether any other steps should be taken (e.g. updating the PR review checklist) in order to catch this type of bug sooner.
Link to discussion: N/A.
[Contributor] If it was decided to create a regression test for the bug, please propose the regression test steps using the template below to ensure the same bug will not reach production again.
[BugZero Assignee] Create a GH issue for creating/updating the regression test once above steps have been agreed upon.
Link to regression test: https://github.com/Expensify/Expensify/issues/561469
Regression Test Proposal
Precondition:
Test:
Do we agree 👍 or 👎
ahmedGaber93 commentedon Oct 25, 2025
@brianlee-expensify Checklist has been completed, sorry for the delay 🙏
trjExpensify commentedon Nov 6, 2025
approved $250 for @ahmedGaber93.