No og:image tag appears in the page source
Work through these checks:
- You are viewing a public site page (
/s/{site-slug}/...), not an admin page or the top-level index. Browse pages (the list of all items, page lists) do not get tags; only show pages, an item set's page (/s/{site}/item-set/{id}), the site home and cross-site search do. - Enable OG image generation is ticked at Admin > OG Images > Settings, and the page's resource type is ticked under Generate OG images for.
- Your theme's layout prints
$this->headMeta()inside<head>. If the theme omits it, none of Omeka's meta tags appear either. - Another theme or module is not setting
og:imageafter this module does. The lastheadMetacall for a property wins.
The image URL returns a tiny transparent image
A 1x1 transparent PNG is the module's deliberate fallback. It is served when generation is disabled, when the resource type is not enabled in settings, or when PHP's GD extension is missing. Check the settings first, then php -m | grep gd on the server.
The image URL returns 404
The resource could not be loaded, which usually means the ID is wrong or the resource is private and not visible to an anonymous request. The endpoint runs without a login, so a private item produces a 404 for social crawlers even if you can see it while logged in.
Text renders in a blocky bitmap font
GD was compiled without FreeType, so TrueType text is unavailable and the module falls back to GD's built-in font. Install or enable a GD build with FreeType support (the gd extension with --with-freetype).
The thumbnail area is empty
The image layer's source resolved to an empty string and the fallback was empty too, or the file could not be loaded:
- Items without media have no
item.thumbnail_url; set a Fallback URL such as{{site.logo_url}}on the image layer and add a logo to the site. - Remote URLs are fetched with
file_get_contents, which needsallow_url_fopenenabled and outbound network access. Files in Omeka's localfiles/directory are read from disk instead and do not need network access. - Files in a remote store (for example S3) are treated as remote URLs.
- GD cannot decode the format (for example TIFF). Use a JPEG, PNG, GIF or WebP.
Load the same resource in the editor with Load real data to see which variables are empty.
Shared links still show the old image
Three caches are involved:
- The module's disk cache. Edit the resource or template, use Flush cache on the template row, or Flush all on Admin > OG Images.
- HTTP caches. Responses carry
Cache-Control: public, max-age=86400, so browsers and proxies may keep a copy for a day. - The social network's own scraper cache. Re-scrape the URL in the platform's sharing debugger; without that, the platform keeps whatever it fetched first.
I set the cache TTL to 0 but images are not regenerated on every request
With a TTL of 0 the module renders a fresh image on every request and writes nothing to the disk cache, so stale images are coming from somewhere else. Responses still carry Cache-Control: public, max-age=86400, so your browser, a proxy or the social network's scraper may be serving its own copy; hard-reload the image URL or re-scrape it in the platform's sharing debugger. Remember to restore a non-zero TTL once you have finished designing, since rendering every request is expensive on a busy site.
The Blog Post type is missing
The Blog Post option only appears in the settings, the template list filter, the template form and the site's overrides when the Blog module is installed and active. Activate the Blog module and reload the page.
Saving a site's admin page shows an error under OG Image Templates
The page's Save saves the section's template overrides first. When that fails, nothing on the page is saved: the page stays open with your changes, and the red message under the section says why.
| Message | What to do |
|---|---|
| Invalid or missing CSRF token. Reload the page and try again. | The page was open for more than 12 hours, or your session ended. Reload the page, make your changes again and click Save. |
| You do not have permission to change this site. | Your account may no longer edit the site, for example because your Admin role in its User permissions was removed after the page was loaded. Ask a Global Administrator. |
| Template 12 does not exist. / Template 12 is not of resource type "item". | The template was deleted, or its resource type changed, after the page was loaded. Reload the page and choose again. |
| The overrides could not be saved. | The server did not answer, or answered with an error page (for example after you were signed out). Reload the page, signing in again if asked. |
A site admin can open the settings page
This is by design. Site Admins and Global Admins are granted every action on the module's admin controller, including settings and cache flush. Lower roles cannot see the OG Images sidebar entry at all.
The editor preview differs from the generated PNG
The preview is drawn by the browser's canvas API and the PNG by GD, so text metrics, gradients and shadows differ slightly. Some settings are preview-only: Border radius is not applied by the server. Open the real image URL (from the page source) to check the final result, remembering to flush the cache after each template save if the TTL has not expired.
Saving a template fails with "Layout JSON must be valid JSON."
The raw JSON textarea contains a syntax error, often a trailing comma. Click Toggle raw JSON, fix the JSON or paste a known-good layout, then save. Applying a style preset also replaces the JSON with a valid layout.
Does uninstalling remove my templates?
Yes. Uninstalling drops the og_template and og_site_template tables and deletes the module's settings. Copy the Layout JSON of templates you want to keep before uninstalling. Cached PNG files are left in the cache directory and can be deleted by hand.