gitbutlerapp/gitbutler · warning

Failed to add shell configuration for

Error message

Failed to add shell configuration for {}, skipping...

What it means

Companion warning to the setup_config failure: after logging the underlying error, configure_shell warns 'Failed to add shell configuration for <shell>, skipping...' and continues installation without shell integration. The install still succeeds; completions/PATH setup for that shell are skipped.

Solutions

1. Treat it as non-fatal: complete the install, then add the completions/PATH lines to your rc file by hand.
2. Re-run the installer after fixing rc file permissions.
3. Verify your shell is supported (check cfg.shell.name() in output); use a supported shell or file a feature request.
4. Use --dry-run/verbose output to see exactly which lines would have been added.

# Pre-check that the installer's target rc file exists and is writable
import os, shlex
shell = os.environ.get('SHELL', '')
rc = os.path.expanduser({'bash': '~/.bashrc', 'zsh': '~/.zshrc'}.get(os.path.basename(shell), ''))
ok = bool(rc) and (not os.path.exists(rc) or os.access(rc, os.W_OK))

// Accept the skip and finish the manual step
match cfg.setup_config() {
    Ok(_) => info("shell config updated"),
    Err(err) => { warn("{err}; skipping — add completions manually"); }
}

When it happens

Trigger: Raised in configure_shell (run_installation_impl) when the user accepted automatic config but cfg.setup_config() returned Err, for any of cfg.shell.name()'s shells — permission denied on the rc file, unknown/unparseable shell, or write failure.

Common situations: Same as the underlying failure: read-only or root-owned rc files, dotfile-manager-managed configs, unsupported shells like fish/nushell lacking a template, sandboxed installers.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• {err}
• A 'but' binary already exists at
• Attempting to restore backup
• Cannot pass both --local and --global
• Cannot write to ( )

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/25b5cb29cd19888e. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-installer/src/shell.rs:216

        info(&format!(
            "Detected {} config file: '{}'",
            cfg.shell.name(),
            cfg.config_path.display()
        ));

        let mut missing = Vec::new();
        if !cfg.has_path {
            missing.push("PATH setup");
        }
        if !cfg.has_completions {
            missing.push("shell completions");
        }
        info(&format!("Config file lacks: {}", missing.join(", ")));

        if ui::prompt_for_confirmation("Automatically add missing config?") {
            if let Err(err) = cfg.setup_config() {
                warn(&format!("{err}"));
                warn(&format!(
                    "Failed to add shell configuration for {}, skipping...",
                    cfg.shell.name()
                ));
            }
        } else {
            info(&format!(
                "Skipping auto-configuration for {}",
                cfg.shell.name()
            ));
            info(&format!(
                "For manual setup, add the following to '{}'",
                cfg.config_path.display(),
            ));
            ui::println_empty();
            for line in cfg.generate_missing_shell_config_lines() {
                ui::println(&format!("  {line}"));
            }
        }

View on GitHub (pinned to 58e5313667)