Flutter Web: Marker Image Fails to Load on Map (Unexpected Null Value)

It appears the error happens during the addSymbol step despite image loading successfully. Use the implementation below which includes error handling and logging:

import 'package:flutter/services.dart';
import 'package:maplibre_gl/maplibre_gl.dart';
import 'dart:typed_data';

class MapMarkerManager {
  static const double DEFAULT_ICON_SIZE = 0.5;
  static const String DEFAULT_ICON_NAME = 'custom-marker';
  
  final MapLibreMapController controller;
  
  MapMarkerManager(this.controller);

  /// Adds a marker to the map with comprehensive error handling
  Future<void> addMarkerToMap({
    required String imagePath,
    required LatLng position,
    String? iconName,
    double iconSize = DEFAULT_ICON_SIZE,
    double? iconRotation,
  }) async {
    final String markerIconName = iconName ?? DEFAULT_ICON_NAME;
    
    try {
      // Step 1: Load and validate the image
      final Uint8List? imageData = await _loadAndValidateImage(imagePath);
      if (imageData == null || imageData.isEmpty) {
        throw Exception('Failed to load valid image data from $imagePath');
      }

      // Step 2: Add image to the map style
      await _addImageToStyle(markerIconName, imageData);

      // Step 3: Create symbol options with null checks
      final symbolOptions = SymbolOptions(
        geometry: position,
        iconImage: markerIconName,
        iconSize: iconSize,
        iconRotate: iconRotation,
        // Ensure the icon appears above other map features
        iconAnchor: 'bottom',
        draggable: false,
      );

      // Step 4: Add the symbol with error catching
      final symbol = await controller.addSymbol(symbolOptions);
      
      print('[SUCCESS] Marker added successfully with ID: ${symbol.id}');
      return symbol;
    } catch (e, stackTrace) {
      print('[ERROR] Failed to add marker: $e');
      print('[STACK TRACE] $stackTrace');
      rethrow;
    }
  }

  /// Load and validate image data
  Future<Uint8List?> _loadAndValidateImage(String imagePath) async {
    try {
      print('[DEBUG] Loading image from: $imagePath');
      final ByteData data = await rootBundle.load(imagePath);
      final Uint8List bytes = data.buffer.asUint8List();
      
      if (bytes.isEmpty) {
        throw Exception('Image data is empty');
      }
      
      print('[DEBUG] Image loaded successfully: ${bytes.length} bytes');
      return bytes;
    } catch (e) {
      print('[ERROR] Failed to load image: $e');
      return null;
    }
  }

  /// Add image to map style with validation
  Future<void> _addImageToStyle(String iconName, Uint8List imageData) async {
    try {
      // Check if the image already exists in the style
      await controller.removeImage(iconName).catchError((e) {
        // Ignore errors if the image doesn't exist
        print('[DEBUG] No existing image to remove: $e');
      });

      // Add the new image
      await controller.addImage(iconName, imageData);
      print('[DEBUG] Image added to map style: $iconName');
    } catch (e) {
      print('[ERROR] Failed to add image to style: $e');
      throw Exception('Failed to add image to map style: $e');
    }
  }
}

// Usage example
class MapScreen extends StatefulWidget {
  @override
  _MapScreenState createState() => _MapScreenState();
}

class _MapScreenState extends State<MapScreen> {
  MapLibreMapController? _mapController;
  MapMarkerManager? _markerManager;

  Future<void> _onMapCreated(MapLibreMapController controller) async {
    setState(() {
      _mapController = controller;
      _markerManager = MapMarkerManager(controller);
    });

    // Wait for the map style to load completely
    await Future.delayed(Duration(milliseconds: 500));

    try {
      await _markerManager?.addMarkerToMap(
        imagePath: 'images/marker.png',
        position: LatLng(40.7342891, -73.9910334),
        iconSize: 0.5,
      );
    } catch (e) {
      print('[ERROR] Failed to add marker: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return MapLibreMap(
      onMapCreated: _onMapCreated,
      initialCameraPosition: CameraPosition(
        target: LatLng(40.7342891, -73.9910334),
        zoom: 13.0,
      ),
      styleString: "YOUR_MAPLIBRE_STYLE_URL",
    );
  }
}

Create an instance of MapMarkerManager in your map screen:

final markerManager = MapMarkerManager(_mapController);

Call the addMarkerToMap method:

await markerManager.addMarkerToMap(
  imagePath: 'images/marker.png',
  position: LatLng(40.7342891, -73.9910334),
);

Here are some additional troubleshooting tips:

• Make sure your marker image isn’t too large. A size of 32×32 or 64×64 pixels is recommended.

• Check your pubspec.yaml formatting:

    flutter:
      assets:
        - images/marker.png  # Make sure there's exactly two spaces before the hyphen

• If the marker still doesn’t appear, try adjusting the iconSize parameter – sometimes the default size might be too small or large depending on your image.