helix-editor/helix · error

unexpected short arg {}

Error message

unexpected short arg {}

What it means

helix-term's CLI parser (Args::parse_args in args.rs) accepts only three clusterable short flags: 'v' (verbosity, repeatable), 'V' (print version), 'h' (help). Every character after a single dash is matched individually; any character outside {v, V, h} bails immediately and startup aborts. Value-taking flags like -g/-c/-w have their own match arms and are not part of the cluster loop.

Source

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

                                "--working-dir specified does not exist or is not a directory"
                            )
                        }
                    }
                    None => {
                        anyhow::bail!("--working-dir must specify an initial working directory")
                    }
                },
                arg if arg.starts_with("--") => {
                    anyhow::bail!("unexpected double dash argument: {}", arg)
                }
                arg if arg.starts_with('-') => {
                    let arg = arg.get(1..).unwrap().chars();
                    for chr in arg {
                        match chr {
                            'v' => args.verbosity += 1,
                            'V' => args.display_version = true,
                            'h' => args.display_help = true,
                            _ => anyhow::bail!("unexpected short arg {}", chr),
                        }
                    }
                }
                "+" => line_number = usize::MAX,
                arg if arg.starts_with('+') => {
                    match arg[1..].parse::<usize>() {
                        Ok(n) => line_number = n.saturating_sub(1),
                        _ => insert_file_with_position(arg),
                    };
                }
                arg => insert_file_with_position(arg),
            }
        }

        // push the remaining args, if any to the files
        for arg in argv {
            insert_file_with_position(&arg);
        }

View on GitHub (pinned to 079a789e8c)

Solutions

1. Replace the short flag with the documented long form: --tutor, --strict, --health [LANG], -g/--grammar fetch|build, -c/--config <path>, --log <path>, -w/--working-dir <dir>, --vsplit, --hsplit.
2. If the cluster itself was a typo (e.g. -vq), drop the invalid characters and keep only v/V/h (e.g. -vv).
3. Run `hx --help` to confirm the exact flag set of the installed version.
4. Re-test wrapper scripts and aliases after every helix upgrade.

Example fix

# before: fails on 't'
hx -vt main.rs
# after
hx -vv --tutor main.rs

# shell wrapper: reject short flags outside {v,V,h} before launching
for a in "$@"; do
  case "$a" in
    -[!vVh-]*) echo "unsupported short flag: $a" >&2; exit 2 ;;
  esac
done
exec hx "$@"

When it happens

Trigger: Running `hx -t`, `hx -x file.rs`, or a mixed cluster like `hx -vq`. Also single-dash misspellings of long options: `hx -config x.toml` fails on 'c', `hx -tutor` fails on 't', `hx -help` fails on 'e'.

Common situations: Vim/emacs muscle memory (flags like -t, -e, -R that helix does not have); wrapper scripts written for a different helix version after flags were added/renamed; typos in shell aliases.

Related errors

• expected a path to file, but found a directory: {file:?}. (t
• can only set a split once of a specific type
• --grammar must be followed by either 'fetch' or 'build'
• --config must specify a path to read
• --log must specify a path to write

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