diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
index 5df18e2e1..6d064b7e2 100644
--- a/docs/upgrade-guide.md
+++ b/docs/upgrade-guide.md
@@ -29,6 +29,8 @@ function App() {
 }
 ```
 
+If you installed `mapbox-gl` from a placeholder such as `npm:empty-npm-package@^1.0.0` as suggested by the previous version's documentation, it should be removed from your package.json.
+
 - The `@types/mapbox-gl` dependency has relaxed its version constraint. If you use `mapbox-gl` as the base map library, it's recommended to explicitly list `@types/mapbox-gl` in your package.json with a version matching that of `mapbox-gl` (v1 or v2). This package is no longer required by the non-mapbox code path, and may be further demoted to an optional peer dependency in a future release.
 - If you use the `Map` component as a child of the `DeckGL` component from `deck.gl`, upgrade `deck.gl` to `>=8.9.18`.