FAQs

Troubleshooting

No og:image tag appears in the page source

Work through these checks:

  1. You are viewing a public site page (/s/{site-slug}/...), not an admin page or the top-level index. Browse pages (item lists, page lists) do not get tags; only show pages, the site home and cross-site search do.
  2. Enable OG image generation is ticked at Admin > OG Images > Settings, and the page's resource type is ticked under Generate OG images for.
  3. Your theme's layout prints $this->headMeta() inside <head>. If the theme omits it, none of Omeka's meta tags appear either.
  4. Another theme or module is not setting og:image after this module does. The last headMeta call 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 needs allow_url_fopen enabled and outbound network access. Files in Omeka's local files/ 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:

  1. The module's disk cache. Edit the resource or template, use Flush cache on the template row, or Flush all on Admin > OG Images.
  2. HTTP caches. Responses carry Cache-Control: public, max-age=86400, so browsers and proxies may keep a copy for a day.
  3. 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 form and the site overrides when the Blog module is installed and active. Activate the Blog module and reload the page.

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.

Log in for Support