Error: Feature description cannot be empty or contain only w

Error message

Error: Feature description cannot be empty or contain only whitespace

What it means

After flag parsing, all remaining positional arguments are joined into the feature description. If the user passed positional text (rest is non-empty) but it strips to empty — only whitespace — the script rejects it with this error instead of silently creating a whitespace-named branch; if nothing positional was passed at all it prints generic usage instead.

Source

Thrown at scripts/python/create_new_feature.py:155

        elif arg == "--timestamp":
            use_timestamp = True
        elif arg in {"--help", "-h"}:
            sys.stdout.write(_help_text(argv0))
            raise SystemExit(0)
        else:
            rest.append(arg)
        i += 1

    description = " ".join(rest).strip()
    if not description:
        if rest:
            print(
                "Error: Feature description cannot be empty or contain only whitespace",
                file=sys.stderr,
            )
        else:
            print(_usage(argv0), file=sys.stderr)
        raise SystemExit(1)

    return Args(
        json_mode=json_mode,
        dry_run=dry_run,
        allow_existing=allow_existing,
        short_name=short_name,
        branch_number=branch_number,
        use_timestamp=use_timestamp,
        description=description,
    )


def _clean_branch_name(name: str) -> str:
    cleaned = re.sub(r"[^a-z0-9]", "-", name.lower())
    cleaned = re.sub(r"-+", "-", cleaned)
    return cleaned.strip("-")

View on GitHub (pinned to bf88c9f9a8)

Solutions

Pass a real description: python create_new_feature.py "Add user login".
In wrapper scripts, default or validate the variable first: DESC="${DESC:-untitled-feature}".
Drop stray empty-string arguments ("" or ' ') from the command line.

Example fix

# before
python create_new_feature.py "$DESC"   # DESC unset/whitespace
# after
DESC="${DESC:-untitled-feature}"
python create_new_feature.py "$DESC"

Defensive patterns

Strategy: validation

Validate before calling

import sys

positional = [a for a in sys.argv[1:] if not a.startswith("--")]
description = " ".join(positional).strip()
if not description:
    sys.exit("Feature description is required")

Try / catch

try:
    args = parse_args(argv)
except SystemExit:
    raise  # fix the invocation; do not retry

Prevention

Default or validate the description variable in wrapper scripts before invoking.
Remove stray quoted empty strings from the command line.
Description must contain at least one non-whitespace character.

When it happens

Trigger: Calling create_new_feature.py " " or with quoted spaces "Add " as the only positional argument; passing flags only but with a stray quoted empty string "" among positionals (rest non-empty, description empty).

Common situations: A wrapper script passing an unset-but-quoted variable ("$DESC" with DESC empty makes rest=[""]); copy-paste commands where the description was deleted but the quotes left; descriptions made only of tabs/newlines.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/24ff470b504017d3. Report an issue: GitHub.