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.
In this article:
Discussion: analyse Hugo’s ‘unable to locate Config file’ error
The ‘Unable to locate Config file’ error message happens when the
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:
- The ‘Config file’ that the error mentions is short for configuration file. That file contains all kinds of configuration variables to specify how Hugo should render our static website (Hugo Docs, 2017a). This makes the configuration file an important part of a successful website build.
- The error says Hugo looked for a configuration file named
Config File "config" Not Found) in the
C:\CodeStudies\hugo-demo\folder. Now the error doesn’t mean we really have no configuration file. It might be that our settings file has a different name or location than Hugo looked for.
Let’s see what can cause Hugo’s ‘unable to locate Config file’ error.
Cause 1) Run
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 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 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 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 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 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.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
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
--config command flag specifies where
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 (
When our configuration file has a custom name or non-standard location, we always need to use the
--config flag with
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.
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/