helix-editor/helix · error · anyhow::Error

can only set a split once of a specific type

Error message

can only set a split once of a specific type

What it means

Argument parser rejects setting a vertical split layout when args.split is already Some(...): '--vsplit' is only accepted while no split direction has been set. The bail fires on the second/duplicate '--vsplit' or on '--vsplit' after '--hsplit'.

Source

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

            let filename = helix_stdx::path::canonicalize(filename);

            args.files
                .entry(filename)
                .and_modify(|positions| positions.push(position))
                .or_insert_with(|| vec![position]);
        };

        argv.next(); // skip the program, we don't care about that

        while let Some(arg) = argv.next() {
            match arg.as_str() {
                "--" => break, // stop parsing at this point treat the remaining as files
                "--version" => args.display_version = true,
                "--help" => args.display_help = true,
                "--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() {

View on GitHub (pinned to 079a789e8c)

Solutions

1. Keep exactly one split flag: either --vsplit or --hsplit, once
2. Fix the alias/script that concatenates both flags
3. To mix layouts, open the first file with a split flag and split further files interactively (spacebar menu) inside the editor

Example fix

# before
hx --vsplit --hsplit a.txt b.txt

# after
hx --vsplit a.txt b.txt

# Deduplicate split flags before invoking hx:
args=$(printf '%s\n' "$@" | grep -E -- '--vsplit|--hsplit' | sort -u | head -1)
# then pass $args once, followed by files

When it happens

Trigger: Command line contains '--vsplit' twice, or '--vsplit' after '--hsplit' (which already set args.split = Some(Horizontal)).

Common situations: Shell aliases or scripts appending both flags ('hx --vsplit --hsplit file' intending one of each); copy-pasted command lines accumulating flags; misunderstanding that the flags apply to ALL opened files, so only one direction can be chosen.

Related errors

• expected a path to file, but found a directory: {file:?}. (t
• --grammar must be followed by either 'fetch' or 'build'
• --config must specify a path to read
• --log must specify a path to write
• --working-dir specified does not exist or is not a directory

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