Help Center

Menu

Troubleshooting remote includes (IncludeURL)

This article provides information on debugging issues when using the IncludeURL macro to remotely include content within a Freemarker template.

For problems with IncludeURL start by checking the generated source code for the search results to see if any errors are printed inside html comments when the remote include is loaded. If an error occurs while attempting to fetch the remote include then the template will return whatever is in the IncludeURL cache for the particular URL (even if the cache has expired).

Error fetching include

Errors while attempting to fetch the remote include could be caused by:

  • The included URL changing (or being redirected elsewhere)

  • Issues relating to HTTPS and the server’s SSL certificate

Updated include is not reflected in the search results template

If an include has been updated but is not displaying it could be that the cache has not yet expired. If you need to refresh the remote include:

  • Try changing the expiry value in the template and publish this (don’t forget to set it back to something sensible after you’ve got the remote include to update)

  • If this doesn’t work you could try adding a fake parameter to the URL (e.g. if you were including http://example.com/includes/header.html try updating the remote include to http://example.com/includes/header.html?1).

  • Finally, restarting the Jetty web service will completely clear the IncludeURL cache.

    Only a system administrator can do this.

Include is not displaying correctly

If the remote include is loading but not displaying correctly:

  • Check the browser web developer tools and inspect both the browser console and network tab.

    • Look out for mixed content or CORS errors that may prevent linked resources such as JS and web fonts from displaying.

    • If there are lots off 404/not found errors to linked resources check that the IncludeURL call is setting the convertrelative parameter and also inspect the code of what is being included to see if there are relative links that are not being converted correctly. Also check for <base href> tags that might break the converted links.

  • If the remote include is displaying the entire remote page within the search results template check the start and end parameters on the IncludeUrl macro to ensure that they are configured correctly and match the source code returned by the remote include.

In some cases it is not possible to use IncludeURL on the remote page because it can’t be converted correctly to a suitable include. If this happens it may be necessary to create a local file to include, or to hardcode the included code within the search template.

See also