Web Files Troubleshooting

This page describes common issues with Web Files in Bloomreach Content and provides solutions for each scenario.

Problem 1: Web File Changes Are Not Pushed to the Repository

When you edit a Web File locally in your IDE, you may not see it at http://localhost:8080/cms/console?path=/webfiles. The following conditions can prevent files from being pushed to the repository:

1. Web File Watch Is Not Enabled

Verify that Web File watch is enabled. For configuration details, see Web Files configuration: Enable web file watch.

2. Editing Files Outside the `repository-data/webfiles` Module

By default, only files in the repository-data/webfiles module are pushed to the repository. To watch additional Maven modules, refer to Web Files configuration: Watching multiple Maven modules.

3. File Size Exceeds the Limit

The default maximum Web File size is 256 KB. To increase this limit, see Web Files configuration: Maximum Web File size limit. Review Web Files Best Practices for alternative approaches, as increasing the file size limit may not be optimal.

4. File Pattern Is Not Included

By default, only specific file patterns are included. To add new patterns, see Web Files configuration: Included files.

Problem 2: Browser Does Not Automatically Reload After Changing CSS, JS, or Freemarker Files

If the browser does not reload automatically after you change a CSS, JS, or Freemarker template file, follow these steps:

Confirm that your changes appear in the repository at http://localhost:8080/cms/console?path=/webfiles. If not, review Problem 1.
If manually refreshing the browser displays your changes, review the following causes:

1. Auto Reload Is Disabled in Configuration

Check the configuration at /hippo:configuration/hippo:modules/autoreload/hippo:moduleconfig and ensure that auto reload is enabled:

enabled: true

2. WebSocket JavaScript Is Not Injected

During local development with mvn cargo.run, a JavaScript snippet is injected into the page to establish a WebSocket connection for change events. In the HTML source, the <head> element should include a <script> tag similar to:

(function(window, console) {

    var AUTO_RELOAD_PATH = "/autoreload",

If this script is missing, your base JSP or Freemarker template may not include the required headContribution. Ensure your base template includes the following headContributions:

<!doctype html>
<html>
  <head>
    <@hst.headContributions categoryExcludes="htmlBodyEnd, scripts" xhtml=true/>
  </head>
  <body>
    <!-- all body html -->
    <@hst.headContributions categoryIncludes="htmlBodyEnd, scripts" xhtml=true/>
  </body>
</html>

For JSP templates, use <hst:headContributions instead of <@hst.headContributions.

Problem 3: HST Does Not Create Correct Links for Web Files or Does Not Render Them

Verify that the hst:default sitemap contains a Web Files sitemap item with the following structure:

/hst:hst:
  /hst:configurations:
    /hst:default:
      /hst:sitemap:
        /webfiles:
          hst:containerresource: true
          hst:namedpipeline: WebFilePipeline
          hst:refId: WEB-FILES-ID 
        /_default_:
          /_any_:
            hst:parameternames: version
            hst:parametervalues: ${1}
            hst:relativecontentpath: ${2}

Problem 4: Uploaded Web Files Are Not Visible in the Browser

If you upload new nodes in the console or update the Binary property using the upload option, but the new file does not appear on the site after saving, check the anti-caching alias.

Update the anti-caching alias at /webfiles/site/webfiles:anticache with a new timestamp value to ensure the browser retrieves the latest version.