Sanity image-url shortcode error: "Cannot read property 'replace' of null

The error "Cannot read property 'replace' of null" suggests that @sanity/image-url is receiving a null value where it expects a valid image reference. This typically happens when the mainImage field is either missing, null, or doesn't have the expected structure.

Here are the most common causes and solutions:

1. Check if the image exists before rendering

The most likely issue is that some posts don't have a mainImage set. Wrap your shortcode in a conditional check:

{% if currentPost.mainImage %}
  <img src="{% croppedUrlFor currentPost.mainImage, 600, 600 %}" alt="{{ currentPost.mainImage.alt }}">
{% endif %}

2. Verify your GROQ query includes image metadata

Make sure your query that fetches posts includes the complete image object structure. Your query should look something like:

*[_type == "post"] {
  _id,
  title,
  mainImage {
    asset->{
      _id,
      url
    },
    crop,
    hotspot,
    alt
  }
}

Without the asset-> expansion, you'll only get a reference, not the actual image data that @sanity/image-url needs.

3. Check your shortcode implementation

Your Eleventy shortcode should handle null values gracefully. Your shortcode might look like:

const imageUrlBuilder = require('@sanity/image-url')
const client = require('./client') // your sanity client

const builder = imageUrlBuilder(client)

eleventyConfig.addShortcode("croppedUrlFor", function(source, width, height) {
  if (!source || !source.asset) {
    return ''; // or return a placeholder image URL
  }
  return builder.image(source).width(width).height(height).url()
});

4. Add null safety to your template

Even with the conditional check, add a fallback for the alt text:

{% if currentPost.mainImage %}
  <img src="{% croppedUrlFor currentPost.mainImage, 600, 600 %}" 
       alt="{{ currentPost.mainImage.alt or 'Blog post image' }}">
{% endif %}

The replace error specifically comes from the URL builder trying to process the asset ID string internally, so ensuring you're passing a complete image object with an asset reference (and handling cases where it's null) should resolve the issue.