Help Center
< All Topics

How To Fix Missing ThumbnailUrl Error In Schema Package

The Missing thumbnailUrl error is a common schema validation issue, especially for VideoObject, ImageObject, and sometimes Article-related schemas. This documentation explains why this error occurs, when it matters, and how to fix it properly using Schema Package.

What Is the thumbnailUrl Property?

thumbnailUrl is a recommended or required property (depending on schema type) that points to a publicly accessible image URL representing the main visual thumbnail of the content.

It is most commonly used in:

  • VideoObject (⚠️ usually required)
  • ImageObject
  • Article, NewsArticle, BlogPosting (via image objects)
  • HowTo (steps with images)

Search engines, especially Google, use thumbnailUrl to:

  • Generate rich results
  • Display video previews
  • Improve visual understanding of content

Why You See the Missing thumbnailUrl Error

You may see this error in:

  • Google Rich Results Test
  • Schema Validator
  • Search Console (Enhancements report)

Common Reasons

  1. No featured image is set on the post or page
  2. Thumbnail field is left empty in Schema Package
  3. Video schema is added without an image
  4. Dynamic mapping failed (e.g., custom field not returning an image)
  5. Invalid image URL (non-public or broken URL)

Which Schema Types Require thumbnailUrl

Schema TypeIs thumbnailUrl Required?
VideoObject✅ Yes (recommended/required)
ImageObject✅ Yes
Article / BlogPosting⚠️ Recommended
HowTo⚠️ Recommended

⚠️ Note: Even if not marked as “required”, missing thumbnailUrl can block rich results eligibility.

How To Fix Missing thumbnailUrl in Schema Package

Method 1: Use Featured Image (Recommended)

Schema Package can automatically use the post featured image as thumbnailUrl.

Steps:

  1. Edit your post or page
  2. Set a Featured Image
  3. Open Schema Package → Schema Package Generator
  4. Edit your schema type (e.g., VideoObject)
  5. Set Thumbnail URL / Image to:
    • Post Featured Image
  6. Save schema

📸 Screenshot Placeholder:

[Screenshot: Selecting Featured Image as Thumbnail]

Method 2: Manually Add Thumbnail URL

Use this method if:

  • The thumbnail is hosted externally
  • You want a custom image different from featured image

Steps:

  1. Open Schema Package Generator
  2. Locate the thumbnailUrl field
  3. Select Custom URL
  4. Paste a full image URL (https:// required)
  5. Save schema

✅ Make sure the image is:

  • Publicly accessible
  • At least 120px wide (Google recommendation)
  • Not blocked by robots.txt

📸 Screenshot Placeholder:

[Screenshot: Adding Custom Thumbnail URL]

Method 3: Use Custom Field / ACF Image

If you are using ACF or custom fields:

Steps:

  1. Ensure your custom field returns:
    • Image URL (not ID unless supported)
  2. In Schema Package mapping:
    • Select Custom Field
    • Choose the image field
  3. Verify preview output

📸 Screenshot Placeholder:

[Screenshot: Mapping ACF Image Field]

Special Case: VideoObject Schema

For VideoObject, thumbnailUrl is critical.

Best Practices:

  • Use video poster image
  • Image size ≥ 1280×720 (recommended)
  • Use JPG or PNG format

Example:

"thumbnailUrl": "https://example.com/video-thumbnail.jpg"

How To Verify the Fix

After adding thumbnailUrl:

  1. Clear cache (if any)
  2. Test URL in:
    • Google Rich Results Test
    • Schema Validator
  3. Confirm no Missing thumbnailUrl error

📸 Screenshot Placeholder:

[Screenshot: Rich Results Test – No Errors]

Common Mistakes To Avoid

❌ Using relative URLs (/image.jpg)

❌ Using blocked images (private CDN)

❌ Leaving thumbnail empty for VideoObject

❌ Mapping image ID instead of URL

SEO Impact of Fixing thumbnailUrl

Fixing this issue helps:

  • Enable video rich results
  • Improve CTR with image previews
  • Avoid Search Console warnings
  • Increase content trust for search engines

Summary

✔ Always provide thumbnailUrl for VideoObject

✔ Use Featured Image whenever possible

✔ Ensure image URLs are public and valid

✔ Validate after saving schema

If you still see errors after following this guide, review your image source or contact Schema Package support.

Table of Contents