gohugoio/hugo · error

errKeyIsEmptyString

errKeyIsEmptyString

Error message

one of the keys is an empty string

What it means

While encoding key/value pairs into a query string, `Querify` rejects any key that is the empty string (tpl/collections/querify.go:76-78, 101-103). An empty key would produce a malformed query fragment like `=value`, so Hugo fails fast instead of emitting a broken URL.

Source

Thrown at tpl/collections/querify.go:26

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package collections

import (
	"errors"
	"net/url"

	"github.com/gohugoio/hugo/common/hmaps"
	"github.com/spf13/cast"
)

var (
	errWrongArgStructure = errors.New("expected a map, a slice with an even number of elements, or an even number of scalar values, and each key must be a string")
	errKeyIsEmptyString  = errors.New("one of the keys is an empty string")
)

// Querify returns a URL query string composed of the given key-value pairs,
// encoded and sorted by key.
func (ns *Namespace) Querify(params ...any) (string, error) {
	if len(params) == 0 {
		return "", nil
	}

	if len(params) == 1 {
		switch v := params[0].(type) {
		case map[string]any: // created with collections.Dictionary
			return mapToQueryString(v)
		case hmaps.Params: // project configuration or page parameters
			return mapToQueryString(v)
		case []string:
			return stringSliceToQueryString(v)
		case []any:

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Find which key is empty — log the input with `{{ warnf "%v" $pairs }}` before calling querify.
2. Filter out entries with empty keys before building the query: `{{ if $k }}{{ $pairs = $pairs | append $k $v }}{{ end }}`.
3. Fix the upstream data (front matter, data file) so every entry has a non-empty key, or provide a `default` value.

Example fix

<!-- before: .key may be empty for some items -->
{{ range $items }}{{ $q = $q | append .key .value }}{{ end }}
<!-- after -->
{{ range $items }}{{ with .key }}{{ $q = $q | append . $.value }}{{ end }}{{ end }}
{{ querify $q }}

{{ range $k, $v := $params }}
  {{ if eq $k "" }}{{ errorf "querify: empty key in params map" }}{{ end }}
{{ end }}

When it happens

Trigger: `{{ querify "" "value" }}`; a map built with `dict` where a key variable evaluated to ""; an even-length slice whose key positions (index 0, 2, 4…) contain empty strings.

Common situations: Keys sourced from front matter or data files where a field is unset and defaults to ""; building query pairs in a loop where the key expression (`.name`, `.key`) is empty for some items; whitespace-only-vs-empty confusion after string manipulation like `trim`.

Related errors

• errWrongArgStructure
• symdiff: failed to convert value: %w
• arguments to symdiff must be slices or arrays
• complement needs at least two arguments
• arguments to complement must be slices or arrays

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