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

Failed to load config: {}

Error message

Failed to load config: {}

What it means

Runtime config reload (refresh_config, used by :config-refresh) failed to load the default config: Config::load_default() errored (TOML parse error, wrong types, or unreadable config.toml) and the anyhow context 'Failed to load config: {}' wraps the underlying toml error including its span/line info.

Source

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

            }
        }

        // Update all the relevant members in the editor after updating
        // the configuration.
        self.editor.refresh_config(&old_editor_config);

        // reset view position in case softwrap was enabled/disabled
        let scrolloff = self.editor.config().scrolloff;
        for (view, _) in self.editor.tree.views() {
            let doc = doc_mut!(self.editor, &view.doc);
            view.ensure_cursor_in_view(doc, scrolloff);
        }
    }

    fn refresh_config(&mut self) {
        let mut refresh_config = || -> Result<(), Error> {
            let default_config = Config::load_default()
                .map_err(|err| anyhow::anyhow!("Failed to load config: {}", err))?;

            // Apply any change to editor.workspace_trust before reading local language config.
            self.editor
                .workspace_trust
                .set_config((&default_config.editor.workspace_trust).into());

            // Update the syntax language loader before setting the theme. Setting the theme will
            // call `Loader::set_scopes` which must be done before the documents are re-parsed for
            // the sake of locals highlighting.
            let lang_loader = helix_core::config::user_lang_loader(&self.editor.workspace_trust)?;
            self.editor.syn_loader.store(Arc::new(lang_loader));
            Self::load_configured_theme(
                &mut self.editor,
                &default_config,
                &mut self.terminal,
                self.theme_mode,
            );

View on GitHub (pinned to 079a789e8c)

Solutions

  1. Read the inner error: the toml message pinpoints line and column of the invalid entry - fix config.toml at that location
  2. Validate quickly: 'hx --health' also loads config and reports errors, or run a TOML linter / 'tomlq .' on config.toml
  3. After a Helix upgrade, diff your config against the current default config.toml / docs for renamed or retyped keys
  4. Once fixed, re-run ':config-refresh' or restart hx

Example fix

# before (config.toml) - string where int expected
scrolloff = "5"

# after
scrolloff = 5
Defensive patterns

Strategy: try-catch

Validate before calling

# Validate TOML after every edit, before refreshing inside hx:
tomlq '.' ~/.config/helix/config.toml > /dev/null && echo config-ok

Try / catch

// refresh_config already returns Result and is surfaced by :config-refresh;
// in your own code keep the old config on failure (Helix does this - it maps
// the error and keeps running with the previous config):
if let Err(e) = app.refresh_config() {
    editor.set_error(format!("{e:#}")); // old config stays active
}

Prevention

When it happens

Trigger: Editing config.toml and running ':config-refresh' (or triggering a reload) while the file has a syntax error, a duplicated key, or a value of the wrong type (e.g. scrolloff = "5" instead of an integer). The inner error string contains the TOML error with line/column.

Common situations: Live-editing config and refreshing without validating; merging snippets from docs with different types across a Helix upgrade (config keys renamed/retyped in newer versions); stray quotes/brackets; accidentally saving a partial write.

Related errors

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