What causes "%s cannot be empty" in gastownhall/beads?

Provide actual non-whitespace content for the text source.

%s cannot be empty

Error message

%s cannot be empty

What it means

requireTextFromSources in cmd/bd/flags.go collects text from the command's text sources and requires it to be non-blank. When at least one source was provided (provided == true) but the resulting text is empty or whitespace-only after TrimSpace, it fails with '<noun> cannot be empty'. This distinguishes 'you passed a source but it contained nothing' from 'you passed no source at all' (error 613).

Source

Thrown at cmd/bd/flags.go:327

	cmd.Flags().String("file", "", "Read "+noun+" from file")
	cmd.MarkFlagsMutuallyExclusive(append([]string{"stdin", "file"}, textFlags...)...)
}

// requireTextFromSources resolves body text like textFromSources and owns the
// shared empty-text policy: text from an explicit source must be non-blank
// ("<noun> cannot be empty"), and with no source at all the error lists the
// command's accepted sources via hint (e.g. "use positional args, --stdin, or
// --file").
func requireTextFromSources(noun, hint string, src textSources) (string, error) {
	text, provided, err := textFromSources(src)
	if err != nil {
		return "", err
	}
	if strings.TrimSpace(text) != "" {
		return text, nil
	}
	if provided {
		return "", fmt.Errorf("%s cannot be empty", noun)
	}
	return "", fmt.Errorf("no %s provided (%s)", noun, hint)
}

// registerPriorityFlag registers the priority flag with a specific default value.
func registerPriorityFlag(cmd *cobra.Command, defaultVal string) {
	cmd.Flags().StringP("priority", "p", defaultVal, "Priority (0-4 or P0-P4, 0=highest)")
}

View on GitHub (pinned to 71377f2769)

Solutions

Provide actual non-whitespace content for the text source.
Check that the --file passed contains the expected text (wc -c file).
In scripts, verify the variable or upstream command output is non-empty before invoking bd.
If no content exists yet, omit the flag so the command fails with the clearer 'no <noun> provided' message or prompts appropriately.

Example fix

// before
EMPTY=""
bd create "$EMPTY"            # "text cannot be empty"
// after
if [ -n "$DESC" ]; then bd create "$DESC"; fi

Defensive patterns

Strategy: validation

Validate before calling

// shell: reject empty input before invoking
DESC=$(cat notes.txt)
[ -n "$(echo "$DESC" | tr -d '[:space:]')" ] || { echo "description is empty" >&2; exit 1; }

Prevention

Trim and check text content before passing it to --stdin/--file.
Check files with [ -s file ] to ensure they are non-empty.
Guard pipelines: fail early if the producing command outputs nothing.
Quote and default shell variables to catch unset/empty cases.

When it happens

Trigger: Calling a command with --stdin or --file (or positional text) where the supplied content is empty or only whitespace, e.g. `echo "" | bd create --stdin`, or an empty --file, or passing "" as positional text.

Common situations: A file that exists but is empty or contains only newlines; a pipeline producing no output (grep with no matches piped into --stdin); a variable in a script that was unset/empty; passing "" as an argument accidentally via shell variable expansion.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/511926d6d3b066b4. Report an issue: GitHub.