Work faster and get better results by blocking distracting websites while you work »

How to fix Hugo’s ‘unable to locate Config file’ error?

Situation: You came across the ‘unable to locate Config file’ Hugo error and would like to know what causes that error and how to fix it.

Discussion: analyse Hugo’s ‘unable to locate Config file’ error

The ‘Unable to locate Config file’ error message happens when the hugo or hugo server command cannot find the configuration file (GitHub, 2018). The full error message on the command line looks like:

C:\CodeStudies\hugo-demo>hugo server
Error: Unable to locate Config file. Perhaps you need to create a new site.
       Run `hugo help new` for details. 
       (Config File "config" Not Found in "[C:\\CodeStudies\\hugo-demo]")

Let’s unwrap this error to see what’s going on:

Let’s see what can cause Hugo’s ‘unable to locate Config file’ error.

Cause 1) Run hugo or hugo server from the wrong folder

The first cause for a ‘missing’ configuration file is that Hugo simply looked in the wrong folder. When we execute the hugo or hugo server command to build or serve our static website, Hugo assumes that the command line’s current folder is our website folder (Hugo Docs, 2017b). In other words, we don’t specify a path to where our static website files are. Instead we simply run those commands in the folder that contains our website.

That folder with our website is also called Hugo’s root or main folder, and is for Hugo the top directory with all files needed to build our website. For instance, it contains the /content/ subdirectory with our content files, /themes/ with the assets and templates from our theme(s), and /static/ for all our static files. While each Hugo root directory looks different based on the project’s needs, a typical main folder looks like:

my-hugo-website
├── archetypes/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
└── config.toml

When the current folder in our command line doesn’t have those folders, we likely try to run the hugo or hugo server commands inside the wrong directory. In that case we fix the ‘unable to locate Config file’ error message by navigating to the proper directory and run Hugo from there.

Cause 2) Not made a Hugo website yet

When we do execute hugo or hugo server from the right folder but still get the ‘unable to locate Config file’ error, we probably need to make a Hugo website in that folder first.

We create a new Hugo website with the hugo new site "folderName" command (Hugo Docs, 2017c). Before we run that command we first navigate to the directory where the Hugo website directory should come. Then we make the new website with hugo new site. That has Hugo make a website skeleton that includes a configuration file.

That process looks like the following when you use PowerShell as your command line. First we navigate to the folder where our new website should come:

C:\CodeStudies\hugo-demo>cd C:\Websites

C:\Websites>

Then we execute hugo new site to make the directory with our new Hugo website:

C:\Websites>hugo new site "personal-blog"
Congratulations! Your new Hugo site is created in C:\Websites\personal-blog.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/, or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

When we navigate into that newly made folder, we see that the Hugo main folder already has the basic layout for a static website:

C:\Websites>cd personal-blog

C:\Websites\personal-blog>tree /F
...
│   config.toml
├───archetypes
│       default.md
├───content
├───data
├───layouts
├───static
└───themes

Here we also have a configuration file: config.toml. And so we can now execute hugo or hugo server in this folder without getting the ‘unable to locate Config file’ error message anymore.

Cause 3) Incorrect named or misplaced configuration file

Two other reasons for the ‘unable to locate Config file’ error are when our configuration file doesn’t have the standard location or the default name.

Hugo looks for the configuration file in its main folder (Hugo Docs, 2017a). That folder has all files Hugo needs to successfully build our static website. And the configuration file is by default placed at the root of that folder. Should we save that settings file somewhere else, then we’ll have to tell Hugo where to find it. We do that with the --config flag of the hugo and hugo server commands (Hugo Docs, 2017b).

Say we put the configuration file in the settings folder of our website project. To have Hugo render the website with that configuration file we type in our command line: hugo server --config=settings/config.toml. This overrides Hugo’s default behaviour, which is to look for a config.toml, config.yaml, or config.json file in the main Hugo folder (Hugo Docs, 2017a).

The ‘unable to locate Config file’ error also happens when our settings file has a non-standard name, like deploy-settings.toml or dev-settings.json. To make Hugo work with those non-typical names we also use the --config command flag. Say we placed those configuration files at the top level of our website folder. Then we build our static website like so: hugo --config=deploy-settings.toml or hugo --config=dev-settings.json.

The --config command flag specifies where hugo or hugo server can find the configuration file. But we cannot change which type of configuration file Hugo accepts: that file has to be in TOML (*.toml), YAML (*.yaml), or JSON (*.json) format.

When our configuration file has a custom name or non-standard location, we always need to use the --config flag with hugo and hugo server. Typing in that extra information every time becomes a bore and is error prone. If you don’t need to, it’s much easier to stick with the default name and location for the configuration file.

Learn more

References

GitHub (2018, January 18). hugo/hugolib/config.go. Retrieved on January 24, 2018, from https://github.com/gohugoio/hugo/blob/master/hugolib/config.go

Hugo Docs (2017a, December 30). Configure Hugo. Retrieved on January 23, 2018 from https://gohugo.io/getting-started/configuration/

Hugo Docs (2017b, September 29). Basic Usage. Retrieved on January 23, 2018 from https://gohugo.io/getting-started/usage/

Hugo Docs (2017c, December 28). hugo new site. Retrieved on January 23, 2018 from https://gohugo.io/commands/hugo_new_site/