Debugging in Hugo made easy

It does not matter if it happens by a typo, syntax mistake or for whatever reason. Errors occur if you are a professional or beginner in any programming language. Here you find tips how to debug in Hugo and see where the mistake is.

Locating the error

It depends on the type of the error, sometimes Hugo simply ignores it, or on the other hand, you get a clear statement in the console. In case you have a message in the console, the message could look like this:

ERROR: 2016/12/18 00:45:34 template.go:132:
template: partials/posts/detail.html:13:10:
executing "partials/posts/detail.html" at <isset>:
wrong number of args for isset:
want 2 got 3 in partials/posts/detail.html

In the case above, the layout has re-rendered, but the area with the error left out blank. Let us dig deeper into the line starting with ERROR.

The first information - 2016/12/18 00:45:34 - we obviously find the date and time the error occurred. In most cases, this data is not very important.

Next fraction - template.go:132 - tells us much more and indicates, who has thrown the error, in this case, the template engine of Hugo. Since you should never blame the messenger of bad news the only information we took over is - template.go does not like something in our code - and the file has a clear name (template) so we can think about there is an error in your templates.

Bingo! The next fraction template: partials/posts/detail.html:13:10 tells us exactly where the error occurs in the semantic of [file]:[line]:[position] so hurry up and open the file and check the particular line. In our test case the content is:

    {{ if isset .Params "headline" "mistake" }}

Ok, something with this line is wrong. Moreover, position 10 is just where isset starts. The information we can carry over to the next round is - in the template detail.html on line 13 there is something wrong with our usage the isset function.

Next fraction - executing "partials/posts/detail.html" at <isset> - confirms our impression once again so we’re on the right track.

Here we are - wrong number of args for isset - tells us exactly that we have passed too much or fewer arguments to the isset function. The correct thing we find out in the next fraction want 2 got 3.

Oops, now I know that I have to pass exactly 2 arguments to isset while I have tried to pass .Params, "headline", and "mistake" to the function. In this case, removing the last argument is the solution.

The correct line in the template would be:

    {{ if isset .Params "headline" }}

Problem solved, not?

Well, I always try to rethink my knowledge now, why did this error happen, is it a bug in the software or a user mistake. In the example case above I would say I should read the documentation about isset once again to avoid such an error in the future. So I have ensured continuous improvements of my skills and move the quality of my work.


Data does not appear in templates

Another very common situation is, that we do not exactly see what kind of data we have available in the current context (.). Lets assume we have a code like this:

<ul>
  {{ range .Params.fruits }}
  <li>
    <strong>{{ .name }}</strong> (Available: {{ .stock }})
  </li>
  {{ end }}
</ul>

Here the assumption is that we have a collection of tables called fruits in the front matter, each fruit has properties name and stock available.

In our simulation case we assume, the only thing we find on the page is:

<ul>
  <li>
    <strong></strong>(Available: )
  </li>
  <li>
    <strong></strong>(Available: )
  </li>
  <li>
    <strong></strong>(Available: )
  </li>
</ul>

Ok! Hey! Where has the name and the stock gone? There is no error in the console, so what can we do to get an insight of what is inside each fruit table.

In our case, we see, that the range properly iterated 3 times through the fruits collection. Perfect, so we know .Params.fruits exists and is an iterable collection.

The easy trick I mostly use to find out what’s available in the context is by adding:

<pre>{{ . | jsonify }}</pre>

Moreover, the content of the context is shown, and I can debug further. Like:

<ul>
  {{ range .Params.fruits }}
  <li>
    <pre>{{ . | jsonify }}</pre>
    <strong>{{ .name }}</strong> (Available: {{ .stock }})
  </li>
  {{ end }}
</ul>

There are plenty of other good hints how to debug in templates in the official documentation.