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

Gutter type can only be `diagnostics`, `spacer`, `line-numbe

Error message

Gutter type can only be `diagnostics`, `spacer`, `line-numbers` or `diff`.

What it means

GutterType is the enum for entries in Helix's gutter config list; FromStr accepts "diagnostics", "spacer", "line-numbers", "diff", and "code-action-hint". Anything else fails when config.toml's gutter array is parsed. Note the error message is stale: it omits "code-action-hint" even though that string parses successfully, so the message undersells the valid set.

Source

Thrown at helix-view/src/editor.rs:924

    /// Show one blank space
    Spacer,
    /// Highlight local changes
    Diff,
    /// Indicator for when code actions are available
    CodeActionHint,
}

impl std::str::FromStr for GutterType {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "diagnostics" => Ok(Self::Diagnostics),
            "spacer" => Ok(Self::Spacer),
            "line-numbers" => Ok(Self::LineNumbers),
            "diff" => Ok(Self::Diff),
            "code-action-hint" => Ok(Self::CodeActionHint),
            _ => anyhow::bail!(
                "Gutter type can only be `diagnostics`, `spacer`, `line-numbers` or `diff`."
            ),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct WhitespaceConfig {
    pub render: WhitespaceRender,
    pub characters: WhitespaceCharacters,
}

impl Default for WhitespaceConfig {
    fn default() -> Self {
        Self {
            render: WhitespaceRender::Basic(WhitespaceRenderValue::None),
            characters: WhitespaceCharacters::default(),

View on GitHub (pinned to 079a789e8c)

Solutions

1. Use only the five accepted values: "diagnostics", "spacer", "line-numbers", "diff", "code-action-hint".
2. Remember the error text is outdated — code-action-hint is valid despite not being listed in the message.
3. Run :config-reload after fixing and check :log-open to confirm the gutter array parses.

Example fix

# before (config.toml)
 gutter = ["line-numbers", "git"] # error

# after
 gutter = ["line-numbers", "diff", "diagnostics"]

const GUTTERS: &[&str] = &["diagnostics", "spacer", "line-numbers", "diff", "code-action-hint"];

for g in &config.gutter {
    if !GUTTERS.contains(&g.as_str()) {
        return Err(anyhow!("invalid gutter '{g}'; valid: {GUTTERS:?}"));
    }
}

fn parse_gutter(s: &str) -> Option<GutterType> {
    match s.to_lowercase().as_str() {
        "diagnostics" => Some(GutterType::Diagnostics),
        "spacer" => Some(GutterType::Spacer),
        "line-numbers" => Some(GutterType::LineNumbers),
        "diff" => Some(GutterType::Diff),
        "code-action-hint" => Some(GutterType::CodeActionHint),
        _ => None,
    }
}

let gutters: Vec<GutterType> = config.gutter.iter()
    .map(|g| g.parse::<GutterType>().map_err(|e| anyhow!("config gutter '{g}': {e}")))
    .collect::<Result<_>>()?;

When it happens

Trigger: Putting an unrecognized string in config.toml's gutter = [...] array, e.g. "git", "blame", "spaces", or a typo like "linenumbers".

Common situations: Users guess gutter names based on other editors' features (git gutter, indent guides) that are not gutter types in this version; copying configs from newer/older Helix versions where the accepted set differs; trusting the error message and not realizing code-action-hint exists.

Related errors

• Command not provided
• Incorrect transport {}
• Language server '{name}' not defined
• Failed to load config: {}
• --config must specify a path to read

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