Debugging Your Hugo Website
Updated 2021-June-27

Page contents


2021-June-23  As of today, this evolving⁠[1] article has been on the web for 2 years.🎂

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

  • Run hugo and hugo server with flags such as:

    • --debug

    • --disableFastRender

    • --gc  (“garbage collector”)

    • --ignoreCache

    • --path-warnings

    • --log

    • -v  (equivalent to --verbose)

    • --verboseLog

    For information about these and other flags, see Infinite Ink’s Hugo CLI page.

  • 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=51000.⁠[2]

  • 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.3 in Infinite Ink’s Hugo Tutorial: Themeless & Gitless Introduction to the Hugo Static Site Generator.

  • 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 TOML in configuration files, front matter, or data files, make sure all TOML tables are at the end. Information about this is in the Now we get crazy section of Nate Finch's Intro to TOML.

  • If you use Mmark[3] 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.


See also


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. Possible port numbers are discussed in In a nutshell: well-known or system ports range from 0 to 1023; registered ports range from 1024 to 49151; dyanamic, private, or ephemeral ports range from 49152 to 65535.
3. Mmark-flavored Markdown is one of the markup languages that Hugo supports. Details about it are at The version of Mmark that Hugo uses is documented at

Comments 👍 📝 😱

Please comment so I know I'm not alone in an infinite void.