Diagnosing Hugo Image Processing Failures with resources.Resize

Recognizable condition

When using Hugo's built-in image processing, a template line such as

{{ $img := resources.Get "photo.jpg" | resources.Resize "300x" }}

may result in one of the following symptoms:

• The image does not appear in the generated site and the browser shows a 404.
• The image is present but retains its original dimensions (no resizing applied).
• The image looks blurry or pixelated because an upscale was requested beyond the source resolution.
• The site build becomes unusually slow when processing many large images.

Cause / diagnostic table

Symptom	Likely cause
No image output / 404	Source file not in assets/, incorrect path (case-sensitive on Linux/macOS), or unsupported input format.
Image appears but dimensions unchanged	Malformed resize specification (e.g., missing "x" separator) or the resize operation returned the original image due to an error.
Image blurry / pixelated	Upscale requested beyond the source image's native resolution.
Build slows dramatically	Processing very large source images (e.g., 20+ MP) without limiting variants or using resource.Fingerprint before resizing.

Ordered checks

1. Verify Hugo version

   Run in your project root:

   hugo version

   Image processing (resources.Resize, Fill, Fit) has been available since Hugo 0.32 (2018) and works in both standard and extended builds. The "extended" label only indicates SCSS/PostCSS support via libsass; it is not required for image processing.

   Required permission: none; just executable access to the Hugo binary.

   Risk: none.

2. Check the asset path and location

   resources.Get only reads files from the project's assets/ directory (or a mounted module). The file must exist at the exact path given, respecting case-sensitivity on Linux/macOS:

   ls -l assets/photo.jpg

   If the file is in static/ instead, resources.Get will not find it. Move it to assets/ or use a relative path from assets/ (e.g., images/photo.jpg).

   Required permission: read access to the asset file.

3. Validate the resize string format

   The spec must follow Hugo's format with an "x" separator. Valid examples:

   • "300x" – width 300px, height calculated to preserve aspect ratio
   • "400x250" – exact width and height (may crop/distort depending on method)
   • "x200" – height 200px, width calculated to preserve aspect ratio

   Incorrect strings like "300", "300px", or "300x"" cause the processor to ignore the request or return the original image.

   Required permission: none.

4. Confirm supported input format

   Hugo's Go-based processor supports these input formats: JPEG, PNG, GIF, WebP, and SVG (rasterized to PNG). Other formats (TIFF, HEIC, AVIF) are not supported. Check the file extension and actual format with:

   file assets/photo.jpg

   Required permission: read access to the file.

5. Look for Hugo warnings during build

   Run hugo or hugo server and watch the console for lines such as:

   WARN  Failed to process image "photo.jpg": ...

   Common warnings indicate: file not found, unsupported format, or invalid resize spec.

   Required permission: none.

6. Clear caches and rebuild

   Run:

   hugo --cleanDestinationDir

   This removes previously generated assets in public/ and forces a fresh image-processing pass, ruling out stale cache issues.

   Required permission: write access to the public/ directory.

Fixes tied to findings

• Move or correct the asset path

  Ensure the source image lives under assets/ (or a subdirectory) and the path in resources.Get matches exactly, including case.

• Adjust the resize specification

  Replace malformed strings with a valid pattern, e.g., change "300" to "300x" or "400x250".

• Convert unsupported formats

  If the source is TIFF, HEIC, or another unsupported format, convert it to JPEG, PNG, or WebP before adding to assets/ (e.g., using ImageMagick's convert or a CI pipeline).

• Reduce source image size or limit processing

  If build time is an issue, downscale source images to a reasonable maximum dimension (e.g., 2000px on the longest edge) before committing them to the repository. This reduces CPU and memory during Hugo's processing.

  Apply resource.Fingerprint after resizing to avoid duplicate work:

  {{ $img := resources.Get "photo.jpg" | resources.Resize "800x" | resources.Fingerprint }}

  Fingerprinting before resizing would create a new hash for each variant, preventing cache reuse.

• Avoid upscaling

  If the source image is smaller than the requested dimensions, Hugo will upscale it, resulting in blur. Either provide a higher-resolution source or use a smaller target size.

Escalation criteria

If the image still does not appear correctly after completing all relevant checks and applying the appropriate fix, collect the following information and seek help:

• Hugo version: hugo version
• Operating system name and version (e.g., ubuntu 22.04, macOS 14, windows 11)
• The exact template snippet causing the problem
• Full console output from a rebuild with --verbose (including any WARN or ERROR lines)
• Output of file assets/your-image.jpg confirming the source format

Post this data to the Hugo Discourse forum or open a GitHub issue in the gohugoio/hugo repository, using the label image-processing.

Verification after fix

After a successful rebuild, inspect the generated public/ directory for a file matching the pattern photo-*.jpg (or the appropriate extension). Verify its dimensions with an image inspection tool:

identify public/images/photo-hu1234567890.jpg
# or
file public/images/photo-hu1234567890.jpg

The reported dimensions should match the requested resize spec (within aspect-ratio preservation).