[Bug]: Unexpectedly found nil while implicitly unwrapping an Optional value

[w8ight]

Mapbox Version

default

React Native Version

0.84.1

Platform

iOS

@rnmapbox/maps version

10.3.0

Standalone component to reproduce

import React from 'react';
import {
  Images,
  MapView,
  ShapeSource,
  LineLayer,
  Camera,
} from '@rnmapbox/maps';

const aLine = {
  type: 'LineString',
  coordinates: [
    [-74.00597, 40.71427],
    [-74.00697, 40.71527],
  ],
};

class BugReportExample extends React.Component {
  render(props) {
    return (
      <MapView style={{flex: 1}}>
        {/* real images object should be passed with at least one png */}
        <Images images={{}} />
        <Camera centerCoordinate={[-74.00597, 40.71427]} zoomLevel={14} />

        <ShapeSource id="idStreetLayer" shape={aLine}>
          <LineLayer id="idStreetLayer" />
        </ShapeSource>
      </MapView>
    );
  }
}

Observed behavior and steps to reproduce

After upgrading to RN 0.84.1, app on iOS started crashing immediately due to usage of the <Images images={images} /> component with a native error saying Unexpectedly found nil while implicitly unwrapping an Optional value. Images object can be as simple as {icon: importedPngIcon}

Does not crash if no images are passed into component

Tried using both images/nativeAssetImages

Happens in both debug and release modes

Xcode 26.4, but happened on 26.3 version as well

import React from 'react';
import {
  Images,
  MapView,
  ShapeSource,
  LineLayer,
  Camera,
} from '@rnmapbox/maps';

const aLine = {
  type: 'LineString',
  coordinates: [
    [-74.00597, 40.71427],
    [-74.00697, 40.71527],
  ],
};

class BugReportExample extends React.Component {
  render(props) {
    return (
      <MapView style={{flex: 1}}>
        {/* real images object should be passed with at least one png */}
        <Images images={{}} />
        <Camera centerCoordinate={[-74.00597, 40.71427]} zoomLevel={14} />

        <ShapeSource id="idStreetLayer" shape={aLine}>
          <LineLayer id="idStreetLayer" />
        </ShapeSource>
      </MapView>
    );
  }
}

Expected behavior

App should not crash

Notes / preliminary analysis

No response

Additional links and references

No response

[TheSolun]

trying to contribute:
I found that error occur due this code, that is inside of the function add Images

RNMBXUtils.fetchImages(bridge, style: style, objects: missingImages, forceUpdate: true) { name, image in self.loadedImages.insert(name) self.imageManager?.resolve(name: name, image: image) }

If I understood correctly, in this scenario bridge is nil and that's why the crash occours

[Magnus-V]

According to xcode the error also occurs in the symbolLayer when an iconImage is set in the styleValue.setImage-function. The brigde is nil.

This causes the crash.

else if (prop == "iconImage") {
      styleValue.setImage(
        bridge: bridge!,  <--- Thread 1: Fatal error: Unexpectedly found nil while unwrapping an Optional value
        style: style,
        oldValue: oldReactStyle?[prop],
        setImageOnLayer: { (_) in self.setIconImage(&layer, styleValue:styleValue) },
        isLayerStillValid: isValid,
        setImageOnLayerLater: { (_) in applyUpdater { (layer: inout SymbolLayer) in self.setIconImage(&layer, styleValue: styleValue) } },
        name: "Symbol.\(prop)"
      )
}

[Magnus-V]

With some help from claude we made these patches. Its a guard for the brigde. Worked for us.

Saved as RNMBXStyle.swift.patch.

patches/@rnmapbox/maps/ios/RNMBX/RNMBXStyle.swift.patch

--- node_modules/@rnmapbox/maps/ios/RNMBX/RNMBXStyle.swift	2026-04-07 14:05:48
+++ node_modules/@rnmapbox/maps/ios/RNMBX/RNMBXStyle.swift	2026-04-07 14:06:57
@@ -26,6 +26,7 @@
     Logger.log(level:.error, message: "Invalid style: \(reactStyle)")
     return
   }
+  guard let bridge = bridge else { return }

   let styleProps = reactStyle.keys
   for prop in styleProps {
@@ -61,7 +62,7 @@
       self.setFillTranslateAnchor(&layer, styleValue:styleValue);
     } else if (prop == "fillPattern") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setFillPattern(&layer, styleValue:styleValue) },
@@ -71,7 +72,7 @@
       )
     } else if (prop == "fillPatternCrossFade") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setFillPatternCrossFade(&layer, styleValue:styleValue) },
@@ -95,6 +96,7 @@
     Logger.log(level:.error, message: "Invalid style: \(reactStyle)")
     return
   }
+  guard let bridge = bridge else { return }

   let styleProps = reactStyle.keys
   for prop in styleProps {
@@ -150,7 +152,7 @@
       self.setLineDasharray(&layer, styleValue:styleValue);
     } else if (prop == "linePattern") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setLinePattern(&layer, styleValue:styleValue) },
@@ -178,7 +180,7 @@
       self.setLineCrossSlope(&layer, styleValue:styleValue);
     } else if (prop == "linePatternCrossFade") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setLinePatternCrossFade(&layer, styleValue:styleValue) },
@@ -212,6 +214,7 @@
     Logger.log(level:.error, message: "Invalid style: \(reactStyle)")
     return
   }
+  guard let bridge = bridge else { return }

   let styleProps = reactStyle.keys
   for prop in styleProps {
@@ -247,7 +250,7 @@
       self.setIconTextFitPadding(&layer, styleValue:styleValue);
     } else if (prop == "iconImage") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setIconImage(&layer, styleValue:styleValue) },
@@ -383,7 +386,7 @@
       self.setTextEmissiveStrengthTransition(&layer, styleValue:styleValue);
     } else if (prop == "iconImageCrossFade") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setIconImageCrossFade(&layer, styleValue:styleValue) },
@@ -521,6 +524,7 @@
     Logger.log(level:.error, message: "Invalid style: \(reactStyle)")
     return
   }
+  guard let bridge = bridge else { return }

   let styleProps = reactStyle.keys
   for prop in styleProps {
@@ -550,7 +554,7 @@
       self.setFillExtrusionTranslateAnchor(&layer, styleValue:styleValue);
     } else if (prop == "fillExtrusionPattern") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setFillExtrusionPattern(&layer, styleValue:styleValue) },
@@ -580,7 +584,7 @@
       self.setFillExtrusionRoundedRoof(&layer, styleValue:styleValue);
     } else if (prop == "fillExtrusionPatternCrossFade") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setFillExtrusionPatternCrossFade(&layer, styleValue:styleValue) },
@@ -882,6 +886,7 @@
     Logger.log(level:.error, message: "Invalid style: \(reactStyle)")
     return
   }
+  guard let bridge = bridge else { return }

   let styleProps = reactStyle.keys
   for prop in styleProps {
@@ -899,7 +904,7 @@
       self.setBackgroundColorTransition(&layer, styleValue:styleValue);
     } else if (prop == "backgroundPattern") {
       styleValue.setImage(
-        bridge: bridge!,
+        bridge: bridge,
         style: style,
         oldValue: oldReactStyle?[prop],
         setImageOnLayer: { (_) in self.setBackgroundPattern(&layer, styleValue:styleValue) },

And
Saved as RNMBXImages.swift.patch.

patches/@rnmapbox/maps/ios/RNMBX/RNMBXImages.swift.patch

--- node_modules/@rnmapbox/maps/ios/RNMBX/RNMBXImages.swift	2026-04-09 00:00:00
+++ node_modules/@rnmapbox/maps/ios/RNMBX/RNMBXImages.swift	2026-04-09 00:00:01
@@ -104,3 +104,4 @@

   func addImages(style: Style, images: [String: Any], oldImages: [String:Any]) {
+    guard let bridge = bridge else { return }
     var missingImages : [String:Any] = [:]

[w8ight]

With this patch the map does not crash the app, but also no image-pins are being displayed