ErrLookup › Background articles › "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries

"must not be empty", "cannot be empty" — required-field validation errors across open-source libraries

"must not be empty", "cannot be empty", and "X is required" errors come from a library's validation guard that rejects a required field when it is missing, an empty string, or only whitespace. Developers hit them when an unset variable, a blank form field, a templated config that stripped a value, or a struct literal with zero-valued fields flows into an API call. Fixing them means finding which field the message names and supplying a real value at the source.

Distilled from 101 documented records across 41 repositories.

Background

These errors are produced at the input-validation boundary of a library or service: a constructor, request handler, config loader, or webhook checks that a mandatory field is present and non-blank before doing any work. The check is almost always a trim-then-test — strings.TrimSpace(request.Text) == "" in beads' comment validation, trim() in zeroclaw's identity persistence, validate_lark_marker_target trimming before any scheme check. That means whitespace-only values are treated exactly like empty ones, which surprises callers who assumed a string of spaces or newlines counts as content. The guard exists because an empty value is rarely a meaningful request: Chroma refuses {"keys": []} in a group_by because zero grouping dimensions is indistinguishable from 'no grouping', which must instead be expressed by omitting group_by or passing {}; gitbutler aborts review creation because a forge requires a title; beads refuses whitespace-only comments because they almost always indicate a shell quoting accident.

From the caller's side these errors usually name the offending field, sometimes with structured detail. zeroclaw's "{field} cannot be empty" reports the first blank field in a fixed order (sop_name, then procedure_markdown, then description); mise's "workspace {kind} ID cannot be empty" tells you whether the provider or project half of a provider:local pair was blank; CodeWhale's ensure_safe_storage_id names the exact kind ('automation id', 'run id', and so on). The error is often deliberately early — Claim in beads validates before opening a transaction because an empty-ID claim can never match a row; zeroclaw's create_proposal validates before leak scanning; zeroclaw's Lark marker validation fires before scheme or workspace checks. So the fix belongs at the value's origin, not where the error surfaces.

Where the empty value comes from is the interesting part. Common origins are optional CLI flags and struct fields defaulted to empty strings, template or YAML merging that stripped entries yet kept the parent object (commented-out YAML keys producing an empty list), i18n lookups returning empty strings for missing locales, QR-pairing or parsing pipelines that extracted nothing, and JSON decoders passing nil bytes to an UnmarshalText (cilium's RuleIPOrCIDR rejects nil outright). Because the message rarely shows the caller the raw value, debugging means tracing upstream to the producer of the empty string rather than retrying.

Behavior around empty values is library-specific and worth checking per record. Chroma makes {} legal — meaning 'no grouping' — for GroupBy.from_dict while Aggregate.from_dict rejects an empty dict, and Select accepts an empty keys list that Aggregate rejects. Excel libraries differ too: excelize treats CustomNumFmt as set only when the pointer is non-nil, so the error fires only for a non-nil pointer to an empty string, while PhpSpreadsheet's Worksheet setCodeName rejects any empty code name but happily generates one when you never call it. Some libraries would rather you omit the field entirely than pass an empty value — CodeWhale tells you to drop a blank provider key so the launch path resolves it from config instead.

Common causes

What usually fixes it

Documented occurrences

…and 81 more across the corpus — use search.

Honest provenance: generated on 2026-09-04 from AI-assisted analysis of the linked records. See how records are made.