What causes "error writing bash-integration .bashrc: %v" in wavetermdev/waveterm?

Ensure the wave data dir and bash-integrations subdir are writable by the running user (chown/chmod).

error writing bash-integration .bashrc: %v

Error message

error writing bash-integration .bashrc: %v

What it means

InitRcFiles wraps the failure of writing the templated .bashrc into Wave's bash-integrations directory. This is an OS-level write or template-render failure from utilfn.WriteTemplateToFile, surfaced verbatim after the %v. Bash blocks lose their integration script if this fails.

Source

Thrown at pkg/util/shellutil/shellutil.go:411

	err = utilfn.WriteTemplateToFile(filepath.Join(zshDir, ".zprofile"), ZshStartup_Zprofile, params)
	if err != nil {
		return fmt.Errorf("error writing zsh-integration .zprofile: %v", err)
	}
	err = utilfn.WriteTemplateToFile(filepath.Join(zshDir, ".zshrc"), ZshStartup_Zshrc, params)
	if err != nil {
		return fmt.Errorf("error writing zsh-integration .zshrc: %v", err)
	}
	err = utilfn.WriteTemplateToFile(filepath.Join(zshDir, ".zlogin"), ZshStartup_Zlogin, params)
	if err != nil {
		return fmt.Errorf("error writing zsh-integration .zlogin: %v", err)
	}
	err = utilfn.WriteTemplateToFile(filepath.Join(zshDir, ".zshenv"), ZshStartup_Zshenv, params)
	if err != nil {
		return fmt.Errorf("error writing zsh-integration .zshenv: %v", err)
	}
	err = utilfn.WriteTemplateToFile(filepath.Join(bashDir, ".bashrc"), BashStartup_Bashrc, params)
	if err != nil {
		return fmt.Errorf("error writing bash-integration .bashrc: %v", err)
	}
	err = os.WriteFile(filepath.Join(bashDir, "bash_preexec.sh"), []byte(BashStartup_Preexec), 0644)
	if err != nil {
		return fmt.Errorf("error writing bash-integration bash_preexec.sh: %v", err)
	}
	err = utilfn.WriteTemplateToFile(filepath.Join(fishDir, "wave.fish"), FishStartup_Wavefish, params)
	if err != nil {
		return fmt.Errorf("error writing fish-integration wave.fish: %v", err)
	}
	err = utilfn.WriteTemplateToFile(filepath.Join(pwshDir, "wavepwsh.ps1"), PwshStartup_wavepwsh, params)
	if err != nil {
		return fmt.Errorf("error writing pwsh-integration wavepwsh.ps1: %v", err)
	}

	return nil
}

func initCustomShellStartupFilesInternal() error {

View on GitHub (pinned to a4447c1563)

Solutions

Ensure the wave data dir and bash-integrations subdir are writable by the running user (chown/chmod).
Recreate the bash-integrations directory (rm -rf then rerun) if it is in a bad state.
Check disk space and filesystem writability on the target volume.
Read the wrapped error text to pinpoint the underlying OS failure.

Defensive patterns

Strategy: validation

Validate before calling

// verify bash-integrations dir is writable before InitRcFiles
if err := os.MkdirAll(bashDir, 0755); err != nil { return err }
if !writable(bashDir) { // e.g. open probe file O_RDWR
	return fmt.Errorf("bash-integrations dir not writable: %s", bashDir)
}

Try / catch

err := shellutil.InitRcFiles(home, binDir)
if err != nil && strings.Contains(err.Error(), "bash-integration .bashrc") {
	os.RemoveAll(bashDir)
	if retryErr := shellutil.InitRcFiles(home, binDir); retryErr != nil {
		return retryErr
	}
}

Prevention

Run Wave under one consistent user account per data dir.
Repair partial first-run states by wiping the bash-integrations directory.
Check for corporate endpoint protection policies blocking writes to dotfile dirs.
Verify the volume is not mounted read-only (common in containers/snapshots).

When it happens

Trigger: InitRcFiles (or InstallRcFiles) reaching the .bashrc write step where <bashDir>/.bashrc cannot be opened for writing: permissions, missing dir, disk full, or template execution error.

Common situations: Corporate-managed machines where the wave data dir is locked down; NFS/ro-mounted home dirs; interrupted first-run leaving partial dirs with wrong ownership.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/1e47343952af9eb2. Report an issue: GitHub.