Onebox configuration and troubleshooting

While users can create rich link previews in their posts using oneboxes (See: Create rich link previews with Onebox), there are some controls available to site administrators, and sometimes when links do not preview as expected, it can be helpful to do a bit of troubleshooting to understand why.

Admin configuration

Site administrators can control many of the onebox settings in the site setting section. To see available settings search for onebox.

Notable settings are:


Behind the scenes, the onebox feature visits the destination page and checks for Open Graph or oEmbed tags, including:

  • site address
  • title
  • feature image
  • description (mandatory)
  • product price

:warning: Please note that Discourse does require the description tag to be present and contain enough text to summarize the page, or the target link will not onebox.

If Onebox is not working as expected, please check the following:

  • Test your site by pasting the link into iFramely; check that the target is using correct OpenGraph or oEmbed meta tags for content. And remember the description text is required in Discourse!
  • Verify that the onebox request to the target website has not been blocked by user-agent. Some WordPress hosts frequently block “unknown” user agents.
  • If an internal link is not displayed as Onebox, make sure it is not in a secure category. For security reasons, internal links only Onebox in public categories or in the same category.
1 Like