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

expected a path to file, but found a directory: {file:?}. (t

Error message

expected a path to file, but found a directory: {file:?}. (to open a directory pass it as first argument)

What it means

Command-line argument validation in Application::new: Helix allows exactly one leading directory (it opens a file picker for it); if any subsequent positional argument is a directory, startup aborts with this error instead of silently mis-opening it.

Source

Thrown at helix-term/src/application.rs:164

            editor.open(&path, Action::VerticalSplit)?;
            // Unset path to prevent accidentally saving to the original tutor file.
            doc_mut!(editor).set_path(None);
        } else if !args.files.is_empty() {
            let mut files_it = args.files.into_iter().peekable();

            // If the first file is a directory, skip it and open a picker
            if let Some((first, _)) = files_it.next_if(|(p, _)| p.is_dir()) {
                let picker = ui::file_picker(&editor, first);
                compositor.push(Box::new(overlaid(picker)));
            }

            // If there are any more files specified, open them
            if files_it.peek().is_some() {
                let mut nr_of_files = 0;
                for (file, pos) in files_it {
                    nr_of_files += 1;
                    if file.is_dir() {
                        return Err(anyhow::anyhow!(
                            "expected a path to file, but found a directory: {file:?}. (to open a directory pass it as first argument)"
                        ));
                    } else {
                        // If the user passes in either `--vsplit` or
                        // `--hsplit` as a command line argument, all the given
                        // files will be opened according to the selected
                        // option. If neither of those two arguments are passed
                        // in, just load the files normally.
                        let action = match args.split {
                            _ if nr_of_files == 1 => Action::VerticalSplit,
                            Some(Layout::Vertical) => Action::VerticalSplit,
                            Some(Layout::Horizontal) => Action::HorizontalSplit,
                            None => Action::Load,
                        };
                        let old_id = editor.document_id_by_path(&file);
                        let doc_id = match editor.open(&file, action) {
                            // Ignore irregular files during application init.
                            Err(DocumentOpenError::IrregularFile) => {

View on GitHub (pinned to 079a789e8c)

Solutions

1. Pass the directory first and only once: 'hx <dir> <files...>' or open dirs in a separate invocation
2. Quote/expand carefully - use nullglob or filter expansions: 'hx $(find . -maxdepth 1 -type f)' style filtering, or zsh 'src/*(.)' glob qualifier for files only
3. If you meant to open a picker for each dir, run them one per invocation

Example fix

# before
hx src/*          # src contains subdirs -> error for the 2nd directory

# after
hx src            # picker for the whole dir
hx $(find src -maxdepth 1 -type f)   # files only

# Shell: filter out all but the first directory before invoking hx
first_dir=""; files=()
for p in "$@"; do
  if [ -d "$p" ] && [ -z "$first_dir" ]; then first_dir="$p"
  elif [ ! -d "$p" ]; then files+=("$p"); fi
done
if [ -n "$first_dir" ]; then exec hx "$first_dir" "${files[@]}"; fi
exec hx "${files[@]}"

When it happens

Trigger: Invoking 'hx dir_a file.txt dir_b' - the first directory becomes a picker, but the second directory (any non-first positional that is a dir) triggers the bail. Mixing directories into a file list in any position after the first argument.

Common situations: Shell glob or foil/expansion pulling directories into the file list (e.g. 'hx src/*' when subdirectories exist); scripts passing '$@' where one entry is a dir; muscle memory from editors that accept dirs anywhere ('code dir file dir').

Related errors

• --working-dir specified does not exist or is not a directory
• 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/25a20ece6ac279d8. Report an issue: GitHub.