Web Files Troubleshooting
In case you are experiencing problems with Web Files, for example not being pushed to the repository, browser auto reloading does not work or Web Files are not rendered by the HST site frontend, you can find here common problems and their solutions.
Problem 1 : My Web File does not get pushed to the repository
at http://localhost:8080/cms/console?path=/webfiles I do not see my Web File I am editing locally in my IDE. One of the following reasons could be your problem
1. Web File watch is not enabled
See Web Files configuration at Enable web file watch how to enable the web file watch.
2. You are editing a file outside repository-data/webfiles module
By default, only repository-data/webfiles files are pushed to the repository. See Web Files configuration at Watching multiple Maven modules how to enable more modules.
3. The file is too large
See Web Files configuration at Maximum Web File size limit how to increase the default file size limit, but, also see Web Files Best Practices for alternative and possibly better solutions because on purpose the default Web File limit is set to 256Kb.
4. The file is not a default included file
See Web Files configuration at Included files how to add new file patterns to also be included.
Problem 2 : After changing a css, js or freemarker template file, the browser does not automatically reload
First of all make sure that the changes of the file end up in the repository below http://localhost:8080/cms/console?path=/webfiles . If not, check out Problem 1. If refreshing the browser yourself works, checkout the following reasons:
1. Auto reload is switched off in configuration
At /hippo:configuration/hippo:modules/autoreload/hippo:moduleconfig, make sure that
enabled: true
2. The javascript for opening a web socket to get change events pushed is not injected
During local development with mvn cargo.run, by default a javascript is injected in the page to open up a web socket. Looking into the source code of the html, you should see in the <head> element a <script> element containing:
(function(window, console) {
var AUTO_RELOAD_PATH = "/autoreload",
If you do not see the above in the source code, most likely your base JSP or freemarker does not contain in the <head> element the right headContribution. Make sure that your base template looks something as below with respect to the headContributions (including the category includes and excludes).
<!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>
In case of JSP, replace <@hst.headContributions with <hst:headContributions.
Problem 3 : HST does not create correct links for Web Files or does not render them correctly
Make sure that there is a Web Files sitemap item with children as follows in the hst:default sitemap:
/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: After uploading Web Files manually, the changes are not visible in the browser
You uploaded new nodes in the console or updated the Binary property with the upload option. After saving the changes the new file does not show up in the site.
Check if you updated the anti-caching alias at /webfiles/site/webfiles:anticache with a new timestamp value.