Troubleshooting | laravel-og-image | Spatie

 SPATIE

  Laravel Open Graph Image
===========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-og-image](https://spatie.be/docs/laravel-og-image/v1)  Advanced-usage  Troubleshooting

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/laravel-og-image/v1)

- [ Introduction ](https://spatie.be/docs/laravel-og-image/v1/introduction)
- [ Requirements ](https://spatie.be/docs/laravel-og-image/v1/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-og-image/v1/installation-setup)
- [ Support us ](https://spatie.be/docs/laravel-og-image/v1/support-us)
- [ Questions and issues ](https://spatie.be/docs/laravel-og-image/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-og-image/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-og-image/v1/about-us)

Basic usage
-----------

- [ How it works ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/how-it-works)
- [ Getting started ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/getting-started)
- [ Customizing screenshots ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/customizing-screenshots)
- [ Defining fallback images ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/defining-fallback-images)
- [ Caching and storage ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/managing-caching-and-storage)
- [ Pre-generating images ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/pre-generating-images)
- [ Clearing generated images ](https://spatie.be/docs/laravel-og-image/v1/basic-usage/clearing-generated-images)

Advanced usage
--------------

- [ Customizing the page URL ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-the-page-url)
- [ Using a custom screenshot driver ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/using-a-custom-screenshot-driver)
- [ Customizing the screenshot layout ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-the-screenshot-layout)
- [ Customizing actions ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-actions)
- [ Troubleshooting ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/troubleshooting)
- [ Using a hosted solution ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/using-a-hosted-solution)
- [ Using Laravel Boost ](https://spatie.be/docs/laravel-og-image/v1/advanced-usage/using-laravel-boost)

 Troubleshooting
===============

###  On this page

1. [ Chrome/Chromium not found ](#content-chromechromium-not-found)
2. [ Blank or broken screenshots ](#content-blank-or-broken-screenshots)
3. [ Timeout issues ](#content-timeout-issues)
4. [ Cache invalidation ](#content-cache-invalidation)
5. [ Debugging with ](#content-debugging-with-ogimage)

Chrome/Chromium not found
---------------------------------------------------------------------------------------------------------------------------------

When using the default Browsershot driver, a Chrome or Chromium binary must be installed on your server. If you get an error about Chrome not being found, make sure it's installed.

On Ubuntu/Debian:

```
apt-get install -y chromium-browser
```

On macOS:

```
brew install --cask chromium
```

If Chrome is installed at a non-standard path, you can configure it using the `configureScreenshot` method in a service provider:

```
use Spatie\OgImage\Facades\OgImage;

OgImage::configureScreenshot(function ($screenshot) {
    $screenshot->setChromePath('/usr/bin/chromium');
});
```

Blank or broken screenshots
-----------------------------------------------------------------------------------------------------------------------------------------

If your screenshots appear blank or have missing styles/fonts, it's usually because CSS or web fonts haven't finished loading before the screenshot is taken.

Common fixes:

- Make sure your CSS is loaded via `` tags in `` (the package preserves the full `` during screenshots)
- For web fonts, ensure they're loaded from ``. The package carries over all `` and `` tags
- Add a delay before the screenshot is taken:

```
use Spatie\LaravelScreenshot\Enums\WaitUntil;

OgImage::configureScreenshot(function ($screenshot) {
    $screenshot->waitUntil(WaitUntil::NetworkIdle0);
});
```

Timeout issues
--------------------------------------------------------------------------------------------------

By default, the package uses a 60-second lock timeout when generating images. If you're generating large images or your server is slow, you may need to increase this:

```
// config/og-image.php
'lock_timeout' => 120,
```

Cache invalidation
--------------------------------------------------------------------------------------------------------------

The package generates a hash based on the HTML content of your OG image template. When the content changes, the hash changes, and a new image is generated automatically.

To manually clear all generated images:

```
php artisan og-image:clear
```

Note that the URL-to-hash mapping lives in your application cache. If you clear the cache (`php artisan cache:clear`), the package will re-cache the mappings on the next page visit, and regenerate screenshots as needed.

Debugging with `?ogimage`
-----------------------------------------------------------------------------------------------------------------------------

Append `?ogimage` to any page URL to preview exactly what will be screenshotted. This renders just the template content at the configured dimensions, using the page's full ``.

```
https://yourapp.com/blog/my-post?ogimage
```

This is useful for:

- Checking if your OG image HTML renders correctly
- Verifying that CSS and fonts are loading
- Testing custom dimensions set via `width` and `height` attributes