gohugoio/hugo · error

too short key: %q

Error message

too short key: %q

What it means

doctree.ValidateKey enforces the invariant format for keys in Hugo's page/document tree: except for the empty root key, a key must be at least 2 characters (a leading '/' plus at least one character). A key of length 1 (e.g. just "/") can't name a real node, so it is rejected to fail fast before corrupting the radix tree.

Source

Thrown at hugolib/doctree/support.go:114

	ctx.eventMu.Lock()
	defer ctx.eventMu.Unlock()
	ctx.events = append(ctx.events, event)
}

// StopPropagation stops the propagation of the event.
func (e *Event[T]) StopPropagation() {
	e.stopPropagation = true
}

// ValidateKey returns an error if the key is not valid.
func ValidateKey(key string) error {
	if key == "" {
		// Root node.
		return nil
	}

	if len(key) < 2 {
		return fmt.Errorf("too short key: %q", key)
	}

	if key[0] != '/' {
		return fmt.Errorf("key must start with '/': %q", key)
	}

	if key[len(key)-1] == '/' {
		return fmt.Errorf("key must not end with '/': %q", key)
	}

	return nil
}

// Event is used to communicate events in the tree.
type Event[T any] struct {
	Name            string
	Path            string
	Source          T

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Pass "" (empty string) for the root node, not "/".
2. Ensure key construction produces "/segment" style paths — check the normalization step that built the key.
3. If hit as a Hugo user, report the site layout/mount that triggers it as a bug with a minimal reproducer.

Example fix

// before
tree.Insert("/", n) // root as "/"
// after
tree.Insert("", n) // root is the empty key

if len(key) < 2 {
    return fmt.Errorf("invalid tree key %q: too short", key)
}

When it happens

Trigger: Calling tree.Insert/InsertIntoValuesDimension (or anything that funnels into ValidateKey) with a one-character key such as "/" or "a". Typically produced by upstream path normalization emitting "/" for a page path instead of the empty root key.

Common situations: Mostly an internal-invariant error: seen when developing Hugo itself or embedding hugolib and constructing doctree keys by hand; occasionally surfaces from pathological content paths/mounts that normalize to a bare slash.

Related errors

• key must start with '/': %q
• key must not end with '/': %q
• redirects must have either From or FromRe set
• failed to create config from result: %w
• failed to create config: %w

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