Incorrect frontmatter termination should produce better error message

[jeffsw]

Fatal errors caused by incorrect Frontmatter termination result in a mostly useless error message. The message should include the filename so user knows what to troubleshoot.

To reproduce, simply create a content file with (for example) YAML frontmatter block that terminates with ... instead of --- (which one might assume is right if they are familiar with YAML but not with Hugo!)

jsw@athena:~/blog$ hugo server
Building sites … ERROR 2018/03/04 09:01:04 unable to read frontmatter at filepos 7040: EOF
Total in 17 ms
Error: Error building site: unable to read frontmatter at filepos 7040: EOF

[vassudanagunta]

@bep I've spent many hours trying to trace template and front matter errors from messages with less info than this one. This is a general source of pain. See #2609, #3171, #4041, #3957, #3514, #1736, #947, #2295 and many others. It's far more painful for people who are not intimate with the Hugo code or nuances in its behavior, so pros like you probably don't feel the pain.

During those many hours above I've inserted some ad-hoc error message details in my dev fork, and I remember coming across this (and your comment within it):

hugo/hugolib/site.go

Lines 1768 to 1780 in e7fda28

	defer func() {
	if r := recover(); r != nil {
	templName := ""
	if templ != nil {
	templName = templ.Name()
	}
	helpers.DistinctErrorLog.Printf("Failed to render %q: %s", templName, r)
	// TOD(bep) we really need to fix this. Also see below.
	if !s.running() && !testMode {
	os.Exit(-1)
	}
	}
	}()

In my dev for I've changed line 1774 to add context (d, the thing being rendered) and also a stack trace because the message returned from recover() had little useful info:

helpers.DistinctErrorLog.Printf("Failed to render %q for %v: %s\n %s", templName, d, r, debug.Stack())

But rather than adding more ad-hoc details to error messages throughout the codebase, why not introduce a richer set of Error structures, and change method signatures to use those rather than the plain built-in error. For example, a PageError that includes info about the offending page. This forces method implementations to consistently provide certain info on error (it's too easy right now just to return a string), and it lends itself to future work on how to handle and report errors in a way most helpful to authors, template developers and hugo developers, and dynamically adjust to different contexts (hugo vs hugo server vs testMode) as your TODO above I think is getting at.

Thoughts?

[bep]

Error structures, and change method signatures to use those rather than the plain built-in error. For example, a PageError

Sure, but I1m not sure why you need to change the method signature. I think something ala os.PathError should cover most needs.

[vassudanagunta]

@bep I was just going to replace my comment with a link to a forum post: https://discourse.gohugo.io/t/more-user-friendly-error-reporting/10852. Continue there?

[bep]

Sure.

[stefl]

I've just been through this as a new Hugo user. To see the effect, take a random content file in your Hugo site, and remove the closing +++ on the frontmatter section, then run hugo serve or huge -w -v. It's super hard to find which file is causing the EOF problem, because the frontmatter termination error comes from code that seems to deal with an IO buffer and doesn't know about file paths.

Using the -debug flag also didn't help. What could be helpful would be to have an output in debug mode that outputs each file as it is being processed? Then you might be able to see the last attempted file, and be able to locate perhaps where the problem might be. That, or some kind of pre-process/validation script you could run to determine if there are any malformed markdown files?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[bep]

This is now fixed.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.