***
## <a name="troubleshooting"></a>TROUBLESHOOTING
* Any javascript-related issues might no longer be valid when
  `No JavaScript lazy` enabled. Unless the exceptions, things that Native
  doesn't support (Blur, BG, Video, etc.) are met, or for those who still
  support old IEs, and cannot ditch lazyloader script, yet.
* Switch to core Bartik for a mo, in case your custom theme is the culprit.
* Blazy and its sub-modules -- Slick, GridStack, etc. are tightly coupled.
  Be sure to have the latest release date or matching versions in the least.
  DEV for DEV, Beta for Beta, etc. Mismatched versions may lead to errors
  especially before having RCs. Mismatched branches will surely be errors.
* Resizing is not supported. Just reload the page. **The main reason**:
  When being resized, the browser gave no data about pixel ratio from desktop
  to mobile, not vice versa. Unless delayed for 4s+, not less, which is of
  course unacceptable.
* Press F12 at any browser, and see the errors at the browser console. Any JS
  error will prevent Blazy from working identified by eternal blue loaders.
* Be sure to view browser console as anonymous, not only as admin users.
* Images are collapsed. Solution: choose one of the Aspect ratio.
* Images or videos aren't responsive. Solution: choose one of the Aspect ratio.
* Images are distorted. Solution: choose the correct Aspect ratio. If unsure,
  choose "fluid" to let the module calculate aspect ratio automatically.

  [Check out few aspect ratio samples](https://cgit.drupalcode.org/blazy/tree/docs/ASPECT_RATIO.md)


### 1. JavaScript Errors
Any references to bLazy library is no longer required for forked version at 2.6.  
**Symptons**:  
Blazy is not defined. Images are gone, only eternal blue loader is
flipping like a drunk butterfly.

**Solution**:  
Ensure that no extras errors. Steps:  

* Switch to core Bartik for a moment in case your theme is the culprit. Any
  theme JS errors might break Blazy. Press F12 at browsers to fix them one by
  one.
* Try disabling `Disconnect` option under IO.  


### 2. BLAZY GRID WITH SINGLE VALUE FIELD (D7 ONLY)
This is no issue at D8. Blazy Grid formatter is designed for multi-value fields.
Unfortunately no handy way to disable formatters for single value at D7. So
the formatter is available even for single value, but not actually
functioning. Please ignore it till we can get rid of it at D7, if possible,
without extra legs.

### 3. MIN-WIDTH
If the images appear to be shrink within a **floating** container, add
some expected width or min-width to the parent container via CSS accordingly.
Non-floating image parent containers aren't affected.

### 4. MIN-HEIGHT
Add a min-height CSS to individual element to avoid layout reflow if not using
**Aspect ratio** or when **Aspect ratio** is not supported such as with
Responsive image. Otherwise some collapsed image containers will defeat the
purpose of lazyloading. When using CSS background, the container may also be
collapsed.

#### SOLUTIONS
Both layout reflow and lazyloading delay issues are actually taken care of
if **Aspect ratio** option is enabled in the first place.

Adjust, and override blazy CSS/ JS files accordingly.

### 5. BLAZY FILTER
Blazy Filter must run after **Align/ Caption filters** as otherwise the required
CSS class `b-lazy` will be moved into `<figure>` elements and make Blazy fail
with JS error due to not finding the required `SRC` and `[data-src]` attributes.
**Align/ Caption filters** output are respected and moved into Blazy markups
accordingly when Blazy Filter runs after them.

Blazy Filter is useless and broken when you enable **Media embed** or
**Display embedded entities**. You can disable Blazy Filter in favor of Blazy
formatter embedded inside **Media embed** or **Display embedded entities**
instead. However it might be useful for User Generated Contents (UGC) where
Entity/Media Embed are likely more for privileged users, editors, admins, alike.
Or when Entity/Media Embed is disabled.

### 6. INTERSECTION OBSERVER API
This API will not be used if `No JavaScript lazy` option enabled unless the
exceptions, things that Native doesn't support (Blur, BG, Video, etc.) are met.
* **IntersectionObserver API** is not loading all images, try disabling
  **Disconnect** option at Blazy UI.
* **IntersectionObserver API** is not working with Slick `slidesToShow > 1`, try
  disabling Slick `centerMode`. If still failing, choose one of the 4 lazy
  load options, except Blazy.

**FYI:**
IO is also used for infinite pager and lazyloaded blocks like seen at IO.module.

### 7. BLUR IMAGE EFFECT
`/admin/config/media/blazy`

The `Image effect` Blur will override `Placeholder` option.
Will use `Thumbnail style` option at Blazy formatters for the placeholder with
fallback to core `Thumbnail` image style.

**For best results:**

* Choose `Aspect ratio` option, non-fluid is better;
* Use similar aspect ratio for both `Thumbnail style` and `Image style`;
* Adjust `Offset` and or `threshold`;
* The smaller the better.

Use `hook_blazy_image_effects_alter()` to add more effects -- curtain, fractal,
slice, whatever.

**Limitations**:
Currently only works with a proper `Aspect ratio` as otherwise collapsed image.
Be sure to add one. If not, add regular CSS `width: 100%` to the blurred
image if doable with your design.

### 8. ASPECT RATIO
**UPDATE 05/02/2020**:
Blazy RC7+ is 99% integrated with Responsive image, including
CSS background and the notorious aspect ratio **Fluid**. The remaining 1% is
some unknown glicthes.

Aspect ratio was never supported for Responsive image till Blazy 2.rc7+, <s>not
fully though. One remaining issue is to make Aspect ratio `Fluid` work for:
CSS background + Picture element.</s>

Any **fixed** Aspect ratio (`4:3, 16:9`, etc) should immediately work as long as
you understand what it means.

Aspect ratio `Fluid` worked with
[**custom breakpoints**](https://www.drupal.org/node/3105243) (deprecated),
<s>not Responsive image, yet. If you want Aspect ratio for Responsive image,
choose anything but `Fluid`.</s>

Any **fixed** Aspect ratio (`4:3, 16:9`, etc), but `Fluid`, wants consistent
aspect ratio down to mobile, which means it won't work with art direction
technique, or Picture element. [Check out few aspect ratio samples](https://cgit.drupalcode.org/blazy/tree/docs/ASPECT_RATIO.md)

Temporary workaround is to add regular CSS `width: 100%` to the controlling
image if doable with your design. And a `min-height` per breakpoint via CSS
mediaqueries.

Aspect ratio fixes many issues with lazyloaded element -- collapsed, distorted,
excessive height, layout reflow, etc., including making iframe fully responsive.
However it doesn't fix everything. Please bear with it.

**If you have display issues, the correct Aspect ratio is your first best bet.**

Depending on your particular issue, **enable or disable**, either way, is your
potential solution. One good sample when Aspect ratio makes no sense is
GridStack gapless grids. Image sizes, hence Aspect ratio, cannot be applied
to gapless grids. Aspect ratio is based on image sizes, not grid sizes.


### 9. BLAZY WITHIN SCROLLING CONTAINER DOES NOT LOAD
`/admin/config/media/blazy`

**Note**: `IO` does not need it, old `bLazy` does.

If you put Blazy within a scrolling container, provide valid comma separated CSS
selectors, except `#drupal-modal, .is-b-scroll`, e.g.: `#my-scrolling-container,
.another-scrolling-container`.

A known scrolling container is `#drupal-modal` like seen at **Media library**.
A scrolling modal with an iframe like **Entity Browser** has no issue since the
scrolling container is the entire DOM. Must know `.blazy` parent container which
has CSS rules containing `overflow` with values anything but `hidden` such as
`auto` or `scroll`. Press `F12` at any browser to inspect elements.

Default to known `#drupal-modal, .is-b-scroll`.
The `.is-b-scroll` can be used when Blazy UI is unreachable without extra legs.

### 10. LINKED FIELD INTEGRATION
Under `Media switcher` option, only `Image to iFrame` makes sense. The rest like
`Image to lightboxes`, or `Image linked to content` will obviously be ignored
since these will output A tag just like what Linked Field does.
Alternatively leave `Media switcher` empty, if no videos are mixed with images.
With `Image to iFrame`, the good thing is video will be still playable, and the
image be linked as required. Best of Both Worlds for real.

### 11. VIEWS GOTCHAS
Blazy provides a simple Views field for File Entity, and Media. Also a Blazy
Grid views style plugin.

When using Blazy formatter within Views, check **Use field template** under
**Style settings**, if trouble with Blazy Formatter as a stand alone Views
output.

On the contrary, uncheck **Use field template**, when Blazy formatter
is embedded inside another module such as Slick so to pass the renderable
array to work with accordingly.

This is a Views common gotcha with field formatter, so be aware of it.
If confusing, just toggle **Use field template**, and see the output. You'll
know which works.

### 12. NATIVE GRID MASONRY
Q: The native grid masonry (_Display style_: native Grid, _Grid large_: any
   single number) doesn't have correct bottom gaps?  
A: It does. Your eyes are likely being tricked. **Solutions**:  

   * Try adding background color to `.grid__content`. Notice even gaps. The
     problem is inner divities do not have 100%. Read more below.
   * If image and applicable, enable `CSS background` using Blazy formatter.
     If using Views, remove extra useless DIVs under `Style settings` by setting
     them all to `None` and keep them with caution. And uncheck
     `Provide default field wrapper elements` under ` Show: Fields Settings`.
     So that Blazy `CSS background` fills in the gaps. Try `Aspect ratio: Fluid`
     to minimize reflow in case useful here.
   * If not or still an issue, manually adjust the image and the inner DIVs of
     `.grid__content` heights to 100%.
   * For text contents, having light background color is enough.
   * Add enough min-height per breakpoint to the grid root container. See
     and override `blazy.nativegrid.css` to better suit your site needs.
   * If you don't want all these headaches, consider a more robust GridStack. It
     may take care these types of issues for you.

### 13. BLAZY IMAGES DO NOT LOAD
Images does not load within hidden tabs, or other hidden containers:  

* `/admin/config/media/blazy`  
* Enable `Load invisible` option.  

Only an issue with old bLazy, not IO, AFAIK. Other than that, be sure to read
back the topmost troubleshooting section.

### 14. BROKEN MODULES
Alpha, Beta, DEV releases are for developers only. Beware of possible breakage.

However if it is broken, unless an update is provided, running `drush cr` during
DEV releases should fix most issues as we add new services, or change things.
If you don't drush, before any module update, always open:

[Performance](/admin/config/development/performance)

And so you are ready to hit **Clear all caches** if any issue.
Only at worst case, know how to run
https://www.drupal.org/project/registry_rebuild safely.

Check out [Update SOP](#updating) for the non-drush users.