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

Directory {:?} is empty. Did you use 'hx --grammar fetch'?

Error message

Directory {:?} is empty. Did you use 'hx --grammar fetch'?

What it means

Raised while building tree-sitter grammars when the grammar's source directory under runtime/grammars/sources/<grammar_id> exists but contains zero entries. The fetch step populates these directories; an empty one means the grammar was never fetched or a previous fetch/clone silently produced nothing.

Source

Thrown at helix-loader/src/grammar.rs:522

        PathBuf::from(&path)
    } else {
        crate::runtime_dirs()
            .first()
            .expect("No runtime directories provided") // guaranteed by post-condition
            .join("grammars")
            .join("sources")
            .join(&grammar.grammar_id)
    };

    let grammar_dir_entries = grammar_dir.read_dir().with_context(|| {
        format!(
            "Failed to read directory {:?}. Did you use 'hx --grammar fetch'?",
            grammar_dir
        )
    })?;

    if grammar_dir_entries.count() == 0 {
        return Err(anyhow!(
            "Directory {:?} is empty. Did you use 'hx --grammar fetch'?",
            grammar_dir
        ));
    };

    let path = match &grammar.source {
        GrammarSource::Git {
            subpath: Some(subpath),
            ..
        } => grammar_dir.join(subpath),
        _ => grammar_dir,
    }
    .join("src");

    build_tree_sitter_library(&path, grammar, target)
}

fn build_tree_sitter_library(

View on GitHub (pinned to 079a789e8c)

Solutions

1. Run 'hx --grammar fetch' first, then 'hx --grammar build'
2. If fetch was already run, verify the directory shown in the error actually has content and disk isn't full / dirs aren't permission-restricted
3. For a grammar added via a custom languages.toml entry, ensure its repository URL is reachable during fetch

Example fix

# before
hx --grammar build   # -> Directory ... is empty. Did you use 'hx --grammar fetch'?

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

// Before building, verify the grammar sources dir is populated:
fn grammar_sources_present(rt: &Path, id: &str) -> bool {
    std::fs::read_dir(rt.join("grammars").join("sources").join(id))
        .map(|mut d| d.next().is_some())
        .unwrap_or(false)
}

When it happens

Trigger: Running 'hx --grammar build' on a fresh checkout or after clearing the runtime grammar dir without ever running 'hx --grammar fetch'; a partial fetch interrupted after creating the directory but before cloning; runtime/grammars/sources manually emptied.

Common situations: New install where the user skipped the fetch step; distro packaging that ships empty grammar dirs; CI cache that preserves directories but not contents; a grammar added by a languages.toml override whose source was never fetched.

Related errors

• Parser compilation failed. Stdout: {} Stderr: {}
• Git command failed. Stdout: {} Stderr: {}
• --grammar must be followed by either 'fetch' or 'build'
• Failed to parse snippet. Remaining input: {}
• Command not provided

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