What causes "invalid value for flag poll: %s" in gohugoio/hugo?

Use a valid Go duration string, e.g. --poll 700ms or --poll 2s.

invalid value for flag poll: %s

Error message

invalid value for flag poll: %s

What it means

Returned by hugoBuilder.newWatcher when the --poll flag's value cannot be parsed into a time.Duration by types.ToDurationE. The --poll flag switches the file watcher to polling mode with the given interval, so an unparsable interval aborts watcher setup. The %s embeds the parse error rather than the raw flag value.

Source

Thrown at commands/hugobuilder.go:322

		return nil, fmt.Errorf("failed to start trace: %w", err)
	}

	return func() {
		trace.Stop()
		f.Close()
	}, nil
}

// newWatcher creates a new watcher to watch filesystem events.
func (c *hugoBuilder) newWatcher(pollIntervalStr string, dirList ...string) (*watcher.Batcher, error) {
	staticSyncer := &staticSyncer{c: c}

	var pollInterval time.Duration
	poll := pollIntervalStr != ""
	if poll {
		pollInterval, err := types.ToDurationE(pollIntervalStr)
		if err != nil {
			return nil, fmt.Errorf("invalid value for flag poll: %s", err)
		}
		c.r.logger.Printf("Use watcher with poll interval %v", pollInterval)
	}

	if pollInterval == 0 {
		pollInterval = 500 * time.Millisecond
	}

	watcher, err := watcher.New(500*time.Millisecond, pollInterval, poll)
	if err != nil {
		return nil, err
	}

	h, err := c.hugo()
	if err != nil {
		return nil, err
	}
	spec := h.Deps.SourceSpec

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Use a valid Go duration string, e.g. --poll 700ms or --poll 2s.
If you meant to just enable polling, still supply an interval (e.g. --poll 500ms, the default interval).
Check shell quoting so the value reaches Hugo intact.

Example fix

# before
hugo server --poll 5sec
# after
hugo server --poll 5s

Defensive patterns

Strategy: validation

Validate before calling

// validate the poll interval before passing it as a flag
if _, err := time.ParseDuration(pollValue); err != nil {
    return fmt.Errorf("invalid --poll value %q: %w", pollValue, err)
}

Type guard

func isValidPoll(s string) bool {
    _, err := time.ParseDuration(s)
    return err == nil
}

Try / catch

if err := cmd.Execute(); err != nil {
    if strings.Contains(err.Error(), "invalid value for flag poll") {
        // show usage: --poll accepts Go durations like 700ms, 2s, 1m
    }
    return err
}

Prevention

Pass Go duration syntax to --poll (e.g. "700ms", "2s"), never bare numbers without units
Validate user-supplied intervals with time.ParseDuration before invoking Hugo
Document accepted duration formats in your wrapper's help text

When it happens

Trigger: Running `hugo server --poll <value>` (or hugo --watch --poll) with a value that isn't a valid duration string or number, e.g. --poll 5x, --poll fast, or malformed unit suffixes.

Common situations: Forgetting the unit (writing `--poll 700ms` works, but exotic or misspelled units like `5sec` don't), copying values from docs with typos, or shell quoting mishaps that mangle the value. Common on network/virtual filesystems (Docker on Windows/macOS, NFS) where polling is needed because inotify events don't propagate.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/8023c10c94b8ffec.json. Report an issue: GitHub ↗.