Use a fallback image

Replicates the MapLibre example Use a fallback image. The coalesce expression tries primary-icon (which no one supplies), misses, and falls back to the declared images: entry.

The complete document

use-a-fallback-image.yaml

# yaml-language-server: $schema=https://docs.maplibre-yaml.org/schema/latest/map.schema.json
# Gallery twin of https://maplibre.org/maplibre-gl-js/docs/examples/use-a-fallback-image/
# coalesce tries each image in turn; the undeclared name misses (one console
# note) and the declared fallback renders.
type: map
id: use-a-fallback-image
config:
  center: [-77.0323, 38.9131]
  zoom: 12
  mapStyle: "https://demotiles.maplibre.org/style.json"
images:
  fallback-marker: "https://maplibre.org/maplibre-gl-js/docs/assets/osgeo-logo.png"
sources:
  points:
    type: geojson
    data:
      type: FeatureCollection
      features:
        - type: Feature
          geometry: { type: Point, coordinates: [-77.0323, 38.9131] }
          properties: {}
layers:
  - id: fallback
    type: symbol
    source: points
    layout:
      icon-image: ["coalesce", ["image", "primary-icon"], ["image", "fallback-marker"]]

What to notice

• The missing primary-icon is handled by the coalesce — MapLibre falls through to the next image without even a warning, exactly as upstream. (A hard-missing reference outside a coalesce gets one console note from the warn-once missing-image handler.)
• On export, literal image names inside icon-image rewrite to the document sprite (mlym:fallback-marker); the undeclared name is left alone, so the emitted style falls back identically.
• Dynamic references (["image", ["get", "icon"]]) resolve live but cannot be rewritten at compile time — use literal names when a document should export cleanly.