description: Run this audit before deploying your production site.
categories: [troubleshooting]
categories: []
keywords: []
menu:
docs:
parent: troubleshooting
weight: 20
weight: 20
---
There are several conditions that can produce errors in your published site which are not detected during the build. Run this audit before your final build.
{{<codecopy=true>}}
```text {copy=true}
HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo && grep -inorE "<\!-- raw HTML omitted -->|ZgotmplZ|\[i18n\]|\(<nil>\)|(<nil>)|hahahugo" public/
description: These questions are frequently asked by new users.
categories: [troubleshooting]
keywords: [faq]
menu:
docs:
parent: troubleshooting
weight: 70
weight: 70
categories: []
keywords: []
---
Hugo’s [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
These are just a few of the questions most frequently asked by new users.
###### An error message indicates that a feature is not available. Why? {#feature-not-available}
An error message indicates that a feature is not available. Why?
: <!-- do not remove preceding space -->
{{% include "/_common/installation/01-editions.md" %}}
{{% include "installation/_common/01-editions.md" %}}
When you attempt to use a feature that is not available in the edition that you installed, Hugo throws this error:
When you attempt to use a feature that is not available in the edition that you installed, Hugo throws this error:
```go-html-template
this feature is not available in this edition of Hugo
```
```go-html-template
this feature is not available in this edition of Hugo
```
To resolve, install a different edition based on the feature table above. See the [installation] section for details.
To resolve, install a different edition based on the feature table above. See the [installation] section for details.
###### Why do I see "Page Not Found" when visiting the home page?
In the `content/_index.md` file:
Why do I see "Page Not Found" when visiting the home page?
: In the `content/_index.md` file:
- Is `draft` set to `true`?
- Is the `date` in the future?
- Is the `publishDate` in the future?
- Is the `expiryDate` in the past?
If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
###### Why is a given page not published?
Why is a given page not published?
: In the `content/section/page.md` file, or in the `content/section/page/index.md` file:
In the `content/section/page.md` file, or in the `content/section/page/index.md` file:
- Is `draft` set to `true`?
- Is the `date` in the future?
- Is the `publishDate` in the future?
- Is the `expiryDate` in the past?
- Is `draft` set to `true`?
- Is the `date` in the future?
- Is the `publishDate` in the future?
- Is the `expiryDate` in the past?
If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
Why can't I see any of a page's descendants?
: You may have an `index.md` file instead of an `_index.md` file. See [details](/content-management/page-bundles/).
###### Why can't I see any of a page's descendants?
What is the difference between an `index.md` file and an `_index.md` file?
: A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/).
You may have an `index.md` file instead of an `_index.md` file. See [details](/content-management/page-bundles/).
Why is my partial template not rendered as expected?
: You may have neglected to pass the required [context](g) when calling the partial. For example:
###### What is the difference between an `index.md` file and an `_index.md` file?
```go-html-template
{{/* incorrect */}}
{{ partial "_internal/pagination.html" }}
A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/).
{{/* correct */}}
{{ partial "_internal/pagination.html" . }}
```
###### Why is my partial template not rendered as expected?
In a template, what's the difference between `:=` and `=` when assigning values to variables?
: Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables).
You may have neglected to pass the required [context](g) when calling the partial. For example:
When I paginate a list page, why is the page collection not filtered as specified?
: You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/).
```go-html-template
{{/* incorrect */}}
{{ partial "_internal/pagination.html" }}
Why are there two ways to call a shortcode?
: Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
###### In a template, what's the difference between `:=` and `=` when assigning values to variables?
Why am I seeing inconsistent output from one build to the next?
: The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems.
Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables).
Why isn't Hugo's development server detecting file changes?
: In its default configuration, Hugo's file watcher may not be able detect file changes when:
###### When I paginate a list page, why is the page collection not filtered as specified?
- Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition
- Running Hugo locally with project files on a removable drive
- Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols
You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/).
In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
###### Why are there two ways to call a shortcode?
Why is my page Scratch or Store missing a value?
: The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
###### Can I use environment variables to control configuration?
You can trigger content rendering with other methods as well. See next FAQ.
###### Why am I seeing inconsistent output from one build to the next?
Which page methods trigger content rendering?
: The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems.
###### Why isn't Hugo's development server detecting file changes?
In its default configuration, Hugo's file watcher may not be able detect file changes when:
- Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition
- Running Hugo locally with project files on a removable drive
- Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols
In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
###### Why is my page Scratch or Store missing a value?
The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
{{ .Store.Get "mykey" }}
```
You can trigger content rendering with other methods as well. See next FAQ.
[`Scratch`]: /methods/page/scratch
[`Store`]: /methods/page/store
###### Which page methods trigger content rendering?
The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
{{% note %}}
For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
> For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
description: Enable logging to inspect events while building your site.
categories: [troubleshooting]
categories: []
keywords: []
menu:
docs:
parent: troubleshooting
weight: 30
weight: 30
toc: true
---
## Command line
@@ -20,40 +14,39 @@ Hugo has four logging levels:
error
: Display error messages only.
```sh
hugo --logLevel error
```
```sh
hugo --logLevel error
```
warn
: Display warning and error messages.
```sh
hugo --logLevel warn
```
```sh
hugo --logLevel warn
```
info
: Display information, warning, and error messages.
```sh
hugo --logLevel info
```
```sh
hugo --logLevel info
```
debug
: Display debug, information, warning, and error messages.
```sh
hugo --logLevel debug
```
```sh
hugo --logLevel debug
```
{{% note %}}
If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
{{% /note %}}
> [!note]
> If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
## Template functions
You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.
description: Tools and suggestions for evaluating and improving performance.
categories: [troubleshooting]
categories: []
keywords: []
menu:
docs:
parent: troubleshooting
weight: 60
weight: 60
toc: true
aliases: [/troubleshooting/build-performance/]
---
@@ -24,9 +18,8 @@ For example, with Microsoft Defender Antivirus:
Then type `hugo.exe` add press the **Add** button.
{{% note %}}
Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation](https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53) for details.
{{% /note %}}
> [!note]
> Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation] for details.
Other virus scanners have similar exclusion mechanisms. See their respective documentation.
@@ -92,21 +85,20 @@ total count
template
: The path to the template, relative to the `layouts` directory.
Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
{{% /note %}}
> [!note]
> Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
## Caching
Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
{{% note %}}
Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
{{% /note %}}
> [!note]
> Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
## Timers
Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates. See [details](/functions/debug/timer/).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Bjørn Erik Pedersen