What causes "--grammar must be followed by either 'fetch' or 'build'" in helix-editor/helix?

Use exactly: hx --grammar fetch or hx --grammar build

--grammar must be followed by either 'fetch' or 'build'

Error message

--grammar must be followed by either 'fetch' or 'build'

What it means

The -g/--grammar option requires exactly one value: 'fetch' or 'build'. Any other following token - including another flag like '-v', a missing value at end of argv, or a misspelled word - hits the catch-all arm and bails with this message.

Source

Thrown at helix-term/src/args.rs:69

                "--strict" => args.strict = true,
                "--tutor" => args.load_tutor = true,
                "--vsplit" => match args.split {
                    Some(_) => anyhow::bail!("can only set a split once of a specific type"),
                    None => args.split = Some(Layout::Vertical),
                },
                "--hsplit" => match args.split {
                    Some(_) => anyhow::bail!("can only set a split once of a specific type"),
                    None => args.split = Some(Layout::Horizontal),
                },
                "--health" => {
                    args.health = true;
                    args.health_arg = argv.next_if(|opt| !opt.starts_with('-'));
                }
                "-g" | "--grammar" => match argv.next().as_deref() {
                    Some("fetch") => args.fetch_grammars = true,
                    Some("build") => args.build_grammars = true,
                    _ => {
                        anyhow::bail!("--grammar must be followed by either 'fetch' or 'build'")
                    }
                },
                "-c" | "--config" => match argv.next().as_deref() {
                    Some(path) => args.config_file = Some(path.into()),
                    None => anyhow::bail!("--config must specify a path to read"),
                },
                "--log" => match argv.next().as_deref() {
                    Some(path) => args.log_file = Some(path.into()),
                    None => anyhow::bail!("--log must specify a path to write"),
                },
                "-w" | "--working-dir" => match argv.next().as_deref() {
                    Some(path) => {
                        args.working_directory = if Path::new(path).is_dir() {
                            Some(PathBuf::from(path))
                        } else {
                            anyhow::bail!(
                                "--working-dir specified does not exist or is not a directory"
                            )

View on GitHub (pinned to 079a789e8c)

Solutions

Use exactly: hx --grammar fetch or hx --grammar build
In scripts, default the variable: ACTION=${ACTION:-fetch} before interpolating
Remember fetch (downloads sources via git) must precede build (compiles them)

Example fix

# before
hx -g        # no value
hx --grammar install   # wrong verb

# after
hx --grammar fetch
hx --grammar build

Defensive patterns

Strategy: validation

Validate before calling

# Script guard: only allow the two legal verbs
ACTION="${1:-fetch}"
case "$ACTION" in fetch|build) ;; *) echo "usage: $0 [fetch|build]"; exit 2;; esac
exec hx --grammar "$ACTION"

Prevention

Use exactly 'hx --grammar fetch' or 'hx --grammar build'
Default-validate interpolated ACTION variables in scripts
Fetch precedes build - chain them explicitly

When it happens

Trigger: 'hx -g' as the last argument; 'hx --grammar install'; 'hx -g fetch extra'; 'hx -g --build' (value starts with '-' so argv.next() yields '--build', not 'build').

Common situations: Assuming a 'grammar install'/'update' subcommand exists; scripts calling 'hx --grammar ${ACTION}' with an unset/empty ACTION variable; typo 'buil'/'fetched'.

Related errors

AI-assisted analysis of helix-editor/helix@079a789e8c (2026-08-16). Data as JSON: /api/errors/13ad7db6eea4188f. Report an issue: GitHub.