Debugging Your Hugo Web Site

An earlier version of this article was in Infinite Ink’s TGIH: Themeless & Gitless Introduction to Hugo in a section called “Debugging tips.”

If there is a problem with a Hugo site that you are developing, here are some things you can try.

  • Use Ctrl-C to stop the Hugo server and then restart it.

  • In your web browser, do a “hard reload” or “hard refresh.” How to do this in many web browsers is in en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache.

  • Run hugo and hugo server with flags such as:

    • --debug

    • --disableFastRender

    • --ignoreCache

    • --path-warnings

    • --log

    • -v (equivalent to --verbose)

    • --verboseLog

  • Check that the port number in your web browser (http://localhost:port) is correct. If you have multiple Hugo servers running, you may need to look at http://localhost:1314. This can happen when you are using multiple terminals.

  • View your site with a different web browser.

  • Explicitly specify a different port, e.g. hugo server -D -p 8888.

  • Put debug code in layout files.

  • Delete the Hugo server cache. To find its location, run hugo config | more and look for the value of cachedir.

  • Delete the resources/ directory that Hugo generates. An example resources/ directory is discussed in Step 5 of TGIH: Themeless & Gitless Introduction to Hugo.

  • In your config file(s) and front matter, make sure that any value that you intend to be a string is not being interpreted as a number, and vice versa. You can force a number to be interpreted as a string by using quotes, for example dateFormat: "2006".

  • If you use Mmark[1] includes, changes in an included file are not noticed by LiveReload. Instead you need to stop and restart the hugo server to view Mmark-include-file changes.

  • 🧐If you have a problem viewing emoji, smart quotation marks (such as ), mathematical symbols (such as ℵ), or any non-ASCII character, make sure your web server’s HTTP configuration and your Hugo source and destination files are all using UTF-8 encoding. UTF-8 is the standard file encoding for the web nowadays.


1. Mmark-flavored Markdown is one of the markup languages that Hugo supports. Details about it are at mmark.nl and miek.nl/2016/march/05/mmark-syntax-document/.