Troubleshooting

This page addresses common issues and misunderstandings when using Image Source Control. We’ll address the ones known to us in this section. Feel free to contact us if you ever run into anything not mentioned here.

See also Compatibility.

Known limitations

Accelerated Mobile Pages (AMP)

On AMP pages, the Overlay displays below the image. Since they don’t support custom JavaScript, on AMP pages we had to remove the script that would move the Overlay on non-AMP pages.

Multiple image source lists

If multiple image source lists are placed on the page or post, only the last one is filled with sources. This could lead to unexpected behavior when using multiple image source lists—for example on archive pages. Additional source lists might only contain the sources for images in the main content. This is relevant if you show sources for images outside the main content.

German umlauts in image URLs

German umlauts (i.e., äöüß) could lead to image URLs not being recognized and appropriate sources not being attached.

WordPress automatically converts these special letters when uploading the file, so this is only an issue with significant manipulation or for external images.

A manual solution to show the overlay for these images is to add the class wp-image-IMAGEID to the <img> tag, with IMAGEID being replaced by the real image ID. E.g., <img src"…" class="wp-image-543">.

Extensionless external images in CSS backgrounds

Image Source Control will not recognize image files that exhibit all of the following traits:

  • they do not possess a proper file extension, e.g., .jpg, .jpeg, .png or .gif
  • they are located on an external server and have been imported through ISC’s “Manage in the media library” feature
  • they are referenced on your page or post by a background-image CSS property

To alleviate this problem, consider one of the following solutions:

  • rename the image file to be suffixed by a proper file extension
  • manually upload the image file to your media library
  • reference the image file’s URL in a regular block in the block editor, e.g., an image block

Please let us know if you notice ISC not recognizing image files in other constellations.

Other media types

Image Source Control does not work out of the box with image types that cannot be uploaded into the WordPress media library by default, including SVG files. As with other media types like videos, ISC could manage sources and display them in lists, but a caption would possibly break their markup.

If an image source overlay is placed above a background image and the background image itself is a link, the links in the overlay text are disabled. Otherwise, the HTML code and layout might break completely.

Dynamic content

Image Source Control cannot detect images loaded dynamically into websites using AJAX, so images loaded this way will not be listed in the image lists with sources. This problem can only be tackled through individual solutions. As a basis, the content returned by AJAX should run through a WordPress filter that ISC could hook into. Ask the developer of that solution about it, and consider hiring me for the implementation.

The unused images feature should not be affected by this since these images are often part of other content and won’t appear as “unused.”

Installation & Licenses

Downloading the plugin

Your browser might be set up to unzip all ZIP files upon completion of the download automatically. Since WordPress expects plugin files to come in ZIP format, you can re-zip them on your hard drive before trying to upload them.

Activating the plugin’s license

Firstly, your license should stay active during any renewal. If not—for example, after performing a manual renewal of your license—, please re-establish your license under Settings > Images Sources > Licenses by clicking the “Update License” button.

During activation of your license, your server needs to connect with ours for a short exchange of the license key. This may cause problems in a few cases. Please try one or more of the following:

  • Please check your account to see whether your license is still valid and whether you have a sufficient number of activations left
  • If the button doesn’t react at all, it could also be caused by a JavaScript issue; please check your browser console for any errors and let us know if Image Source Control causes them

Updating the plugin

You might run into a problem while trying to update Image Source Control. Please check if one of the following corresponds to it:

  • Error message that resembles “The package could not be installed. PCLZIP_ERR_BAD_FORMAT (-10) : Unable to find End of Central Dir Record signature”:
    Please ask your site administrator or web host to install or update the cURL.
  • Error message that resembles “Download failed: Unauthorized”:
    Please follow the steps explained in the previous subsection to check and activate your license.

Image Sources

Image sources are not showing up

When image sources aren’t displayed in your frontend, one reason might be that your website is cached—by one of the popular WordPress caching plugins or by your server software. ISC cannot create the page-image index for cached page views. You can either wait for your cache to update automatically or clear it manually to have it start indexing.

Contact your site administrator or web host if you can’t clear the cache by yourself.

Otherwise, to debug missing sources, please try the following and see when and where source information starts to show up:

  • enable the Per-page as well as Overlay options
  • switch to a default theme like Twenty Twenty-Three
  • if you are using a page builder like Divi or Elementor, create a new page / post without it
  • change the ISC settings to display image sources for images outside the content

Image sources are not updating

Try the following if the image sources are not updating in the Per-page list or the Global list.

  • Double-check the plugin options to ensure that displaying the source is set up as expected.
  • Call the page with the image in the frontend while logging in, circumventing any cache.
  • Disable a caching plugin temporarily.
  • Go do Media > Image Sources and click the “list post-image relations” button. Delete the entry for the post in question and then visit it in the frontend to force a re-index.
  • Run the Indexer on the whole content.
  • Check the list of known limitations on this page.
  • Check the compatibility list with other plugins and themes.

When your site shows random images on every page load, you might want to use this code snippet to circumvent the internal image index.

Image URLs in the frontend don’t match the Media Library

If image sources don’t show up, the cause might be that the URLs in the frontend don’t match the image URLs in the Media Library. This is always due to custom code in plugins or themes.

The problem and solution are explained in detail in Adding overlays to images with dynamic URLs.

Image source fields are not showing up

Block Editor vs. Media Modal

For technical reasons, when editing content in the block editor, the image source fields can only be used either as block options or in the Media Library modal. By default, they are enabled as block options for image-related blocks.

This also means that they would not appear in the Media Library modal that appears when uploading an image to the block editor.

You can switch to the fields showing up in the modal by disabling the option Settings > Image Sources > Miscellaneous settings > Block options.

You can also use this code snippet to enable the input fields in the block editor and media modal at the same time.

Converting Classic text to Blocks

On rare occasions, the input fields of Image Source Control are missing from the block properties in the sidebar—for instance, after converting the content of a post from a Classic block to Blocks.

Restoration of ISC input fields

Simply select the image block, use the button “Upload external image” in the context menu of the block, and the ISC input fields return in their usual position.

The overlay shows in the wrong position

On pages with dynamic elements, e.g., lazy loading images or content added later to the page, the caption could be off.

Using one of these codes, you could switch off the dynamic content injection or refresh the caption position.

The overlay covers a fixed element

If the overlay covers a fixed element, like a fixed header, you need to reduce z-index using CSS for the overlay or increase it for the covered element. For the overlay, you can try this rule, which already reduces the default z-index: 9999.

.isc-source-text { z-index: 100 !important; }Code language: CSS (css)

Data missing after migration

Image source information should be preserved by WordPress when using Tools > Export for media. You can double-check that the wp_postmeta table is included.

Important: After importing that data, the index information that ISC creates is outdated. Clear the meta data as described below on the next website to fix that.

  1. Go to Media > Image Sources
  2. Scroll down and click on clear image-post index

The index is rewritten automatically with every post visited in the frontend. You can also run a rull re-index. You can reach the Indexer under Media > Unused Images > Run Indexer.

When using dedicated Import/Export plugins like WP All Import, you might need to manually match the post meta keys in their import configuration.

Admin Bar Debugger

Our Admin Debugger plugin helps troubleshoot issues with missing image sources on pages. In the admin bar, it lists all images found and indexed by ISC and their assigned image source texts.

You can download the plugin here. Enable it and visit the appropriate frontend pages while logged in as an admin.

Example of the ISC Debugger plugin showing used images in the WordPress admin bar.
Example of the ISC Debugger showing images and attributions in the admin menu.

Debugging options

Under Media > Image Sources, you will find some debug tools you can use when running into problems:

  • Post Index > List post-image relations
    This will display a list of pages and posts and the images ISC found in their content. The Global List is generated from these entries. If you find some images missing, remove the row for that page here, and ISC will reindex it when next visited in the frontend.
  • Post Index > List image-post relations
    This will display a list of images and the pages or posts they are placed in. The Per-page List is generated from these entries.
  • Post > Index > Clear image-post index”
    This will remove the correlation between images and posts. The index is rebuilt automatically when a page or post with images is visited in the frontend.
  • Storage > Clear storage
    This will tell ISC to clear the internal index of image URLs and IDs from the media library to limit the number of database requests in the frontend.

Debug log

The debug log helps you retrace the scripted steps ISC takes whenever a page or post is queried that contains ISC elements. Follow these steps to enable and consult the debug log:

  1. Go to Settings > Image Sources > Miscellaneous settings > Debug log, check the box, and save the settings
  2. In your frontend, open the page or post you would like to log
  3. Append ?isc-log to the URL and hit return to reload it with debugging enabled—mind that you’ll see no change
  4. Find the link to the log in the setting mentioned in step 1. Open the link to see the log file. It is different on each website.

Replace ?isc-log with &isc-log if the URL already contains other GET parameters.

Unchecking the box under Settings > Image Sources > Miscellaneous settings > Debug log will remove the log file.