Imager X 5.0

# Troubleshooting

Things doesn't always go according to plan. If you experience issues with Imager, here are some things you can do to investigate and find a solution yourself, or get more information for when you submit an issue (opens new window).

TIP

There's a nifty, new utility in Imager X 4.0 that provides some of the debug information that would be useful if you have an issue. Please add that when submitting an issue.

# Is it cached?

By default, caching is turned on in Imager, via the cacheEnabled config setting. If caching is turned on and a transform already exists in the imagerSystemPath, most of the transform handling will be skipped. When debugging certain types of issues, like issues with optimizer or external storages, it's essential to either turn off caching, or clearing the relevant caches if that's preferable (can be done from the Imager X utility).

Also note that download of external files is cached accurding to the cacheRemoteFiles and cacheDurationRemoteFiles config settings. This works seperately from the transform-caching and must be disabled/cleared if your issue involves files downloaded from an external source.

# Enable devMode

If you haven't already, enable devMode (opens new window), and make sure that suppressExceptions is set to false. You should now see any exceptions that Imager throws, directly in your browser.

This should give you an hint of what went wrong. If you submit an issue, please provide as much of the stacktrace as possible, but make sure that you anonymize any sensitive details.

# Debug toolbar and logs

Not all errors result in an exception, and you can't always enable devMode. So the next step is to enable the debug toolbar in the "Preferences" section on your user.

With the debug toolbar enabled, go to the "Logs" section, and filter the logs by either choosing "Error" in the "Type" column dropdown, or filter the category column on "imager".

The debug toolbar is nice for debugging errors that occur during a normal page load. But sometimes things happen at odd times. For those, you need to comb through your logs. They are located in storage/logs, and the relevant ones are:

  • web.log for errors that occur during normal web requests.
  • console.log for errors that occur during console requests.
  • queue.log for errors that occur during queue jobs.
  • phperrors.log for errors cast by PHP itself.

Again, you can search for "[error]" or "imager" to find relevant errors.

# Reduce the complexity

Sometimes there's a lot going on in a single transform. Try removing some of the complexity, and maybe you'll be able to more accurately pinpoint what the underlying issue is. Maybe removing that watermark solves it? Or maybe try running optimizers during runtime (through the optimizeType config setting), instead of as a queue job? Or turning off optimizers altogether? Does it happen for all images, or just a specific one?

When you post an issue (opens new window), let us know what you've tried.

# Did anything happen?

If there isn't anything in the logs, make sure to check what's going on in your imagerSystemPath. Did the file get created? At least this will give you an idea if the transform works or not, and maybe it's just an issue with your imagerUrl or upload to an external storage.

# Post an issue

If you're still stumped, please post an issue in the github repository (opens new window). Make sure to supply as much information about your issue as possible, and make sure to follow the issue template. You can use the Imager X utility to get all the relevant information about your environment.

← FAQ →