Brightspot CMS Developer Guide

Troubleshooting images


This section describes the steps for diagnosing and resolving the most common causes of blurry or missing images in published content.

The techniques described in this section assume you are using the Frost theme, which adds a srcset attribute to <img> tags. In other scenarios, you can use similar techniques to identify the cause of a blurry image.

See also:


The following steps help to identify the cause of a blurry image on a published page.

Step 1: Check native image’s size

Brightspot displays images in different sizes depending on the context. If the editor uploaded a very small image, Brightspot likely enlarges it, resulting in a blurry presentation.


Blurry image native size Blurry image native size
Native image

Blurry image author byline Blurry image author byline
Image in author’s byline

Blurry image author bio Blurry image author bio
Image in author’s bio page

Referring to the previous examples, the native image is small, 65 × 65 pixels. The image in the byline is 100 ×100, and in the bio page 240 × 240. At each level of zoom, Brightspot needs to fill in pixels, resulting in a blurry effect.

The best way to check a native image’s size is to view it in a browser or graphic editor. The following instructions apply to the Chrome browser; the procedure for other browsers is similar.

To view a native image:

  1. In a published page, right-click the blurry image, and select Inspect from the popup menu.
  2. In the Elements tab, right-click the img element and select Copy > Copy element.
  3. Paste the element into a text editor.
    • The element contains a srcset attribute for displaying different image sizes on different pixel densities.
    • Each entry in the srcset attribute has the form DIMSurl?NativeImageURLEncoded, as in the following illustration.
      query_parameter_native_url_encoded.svg query_parameter_native_url_encoded.svg
  4. Copy and paste the encoded URL into a decoder, such as URL Decoder.
  5. Paste the decoded URL into your browser. The image you see is the native image uploaded by the editor.

Result:

  • If the image is small, the blurries are due to enlarging the image. Inform the editor to upload a larger image, ideally three times the size of the largest size listed in srcset. (Uploading an image this size allows devices with pixel-density ratios up to 3 to display images without introducing the blurries.)
  • If the native image size is large, the blurries are due to another reason. Save the native image to your local drive, and continue to the next step.

Step 2: Check quality of native image

View the native image you saved in "Step 1: Check native image’s size in your browser."

Result:

  • If the native image is blurry, then no amount of editing (either by Brightspot or by a graphic artist) can make it crisp. Inform the editor to upload a different image.
  • If the image is crisp, the blurries are due to another reason. Continue to the next step.

Step 3: Check native image’s pixel density

Images taken with a low-ppi camera or created on a low-ppi monitor appear blurry on high-ppi screens.

Open the native image in a graphic editor and view the ppi, or use the ImageMagick command identify -format "PPI (x,y): %x x %y\n" filename.ext.

Result:

  • If the native image’s ppi is much smaller than that of the monitor, the client device is adding pixels to compensate, resulting in a blurry image. Inform the editor to upload a higher ppi image, ideally three times the size of the largest size listed in srcset. (Uploading an image this size allows devices with pixel-density ratios up to 3 to display images without introducing the blurries.)
  • If the native image’s ppi is close to that of the native image, search for blurry images on the Internet for other possible resolutions.

Images uploaded to Brightspot can be missing in the preview pane or in a published page. The following steps help to identify the cause of a missing image.

Step 1: Check native image’s URL

Ensure the native image’s URL is valid. The following instructions apply to the Chrome browser; the procedure for other browsers is similar.

To verify a native image’s URL:

  1. In a published page, right-click the missing image, and select Inspect from the popup menu.
  2. In the Elements tab, right-click the img element and select Copy > Copy element.
  3. Paste the element into a text editor.
    • The element contains a srcset attribute for displaying different image sizes on different pixel densities.
    • Each entry in the srcsetsrcset attribute has the form DIMSurl?NativeImageURLEncoded, as in the following illustration.
      query_parameter_native_url_encoded.svg query_parameter_native_url_encoded.svg
  4. Copy and paste the encoded URL into a decoder, such as URL Decoder.
  5. Paste the decoded URL into your browser.

Result:

  • If the image is missing (error 404), or if the URL points to something other than an image, then inform the editor to upload a new image.
  • If the URL appears in your browser, continue to the next step.

Step 2: Check native image’s format

Before delivering an image to a client, Brightspot performs some edits, such as cropping and resizing. On some versions of Brightspot, these operations fail on TIFFs. Use the following procedure to determine if this failure is occurring on your version of Brightspot.

  1. Examine the URL you pasted into the text editor in "Step 1: Check native image’s URL." Does the native URL have a .tif or .tiff extension?
  2. Is there a path parameter format/jpg?

Result:

  • If the answer to 1 is Yes and the answer to 2 is No, then the conversion from TIFF to JPG is failing, and the image appears as if missing. Do one of the following:

    • Inform the editor to convert the image to JPG, PNG, or GIF and upload the image again.
    • Update your theme to include the conversion from TIFF to JPG, PNG, or GIF.
  • In all other cases, continue to the next step.

Step 3: Check for zero-width crops

Some previous versions of Brightspot intermittently injected zero-width crops.

  • Examine the URL you pasted into the text editor in "Step 1: Check native image’s URL."

Result:

  • If there is a path parameter crop/0x0+0+0, contact your Brightspot representative to receive a patch.
  • If there is no crop parameter or if the crop parameter has reasonable dimensions, continue to the next step.

Step 4: Check for access to native image from the DIMS server

At run time, the DIMS server retrieves the native image, performs graphic editing, and delivers the modified image to the client. In this step, you verify the DIMS server has access to the native image.

To check for DIMS access:

  • SSH in to the DIMS server.
  • Use curl or wget to retrieve the missing image, pasting the decoded URL from "Step 1: Check native image’s URL" into the command line.

Result:

  • If the request from the DIMS server fails, perform network debugging to resolve the error. Typical causes are firewalls, timeouts, and allowed/blocked access control.
Previous Topic
Image URLs
Next Topic
View system
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Modules
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Dashboards
Publishing
Workflows
Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
Images
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Shopify
Apple News