wavetermdev/waveterm · error

error writing zsh-integration .zlogin: %v

Error message

error writing zsh-integration .zlogin: %v

What it means

InitRcFiles writes Wave's shell integration scripts (templated rc files) into the app-managed zsh integration directory. This error wraps any failure from utilfn.WriteTemplateToFile when writing .zlogin, typically an OS-level file write failure (permission denied, read-only filesystem, missing parent dir, disk full). Wave surfaces the underlying error with %v so the root cause is appended.

Source

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

	}
	params := map[string]string{
		"WSHBINDIR":      HardQuote(absWshBinDir),
		"WSHBINDIR_PWSH": HardQuotePowerShell(absWshBinDir),
		"PATHSEP":        pathSep,
	}

	// write files to directory
	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)

View on GitHub (pinned to a4447c1563)

Solutions

1. Check permissions on the wave data dir (~/.waveterm or the configured WAVETERM_HOME) and chown/chmod so the running user can write (e.g. chmod -R u+w ~/.waveterm).
2. Free disk space and confirm the filesystem is writable (touch a file in the zsh-integrations dir).
3. Delete the stale zsh-integrations directory so InitRcFiles recreates it fresh, then retry.
4. Read the wrapped %v detail to identify the exact OS error (EACCES vs ENOSPC vs ENOENT) and address that specifically.

Example fix

// before: rc files dir owned by root after sudo install
$ sudo wave  # creates root-owned ~/.waveterm/zsh-integrations
// after: run as normal user, fix ownership
$ sudo chown -R $USER ~/.waveterm && wave

// before InitRcFiles
if err := os.MkdirAll(zshDir, 0755); err != nil { return err }
if fi, err := os.Stat(zshDir); err != nil || !fi.IsDir() { return fmt.Errorf("zsh dir unusable") }
if err := syscallaccess.CheckWritable(zshDir); err != nil { return fmt.Errorf("zsh dir not writable: %w", err) }

if err := shellutil.InitRcFiles(waveDataHome, binDir); err != nil {
	if strings.Contains(err.Error(), "zsh-integration .zlogin") {
		log.Printf("recoverable rc write failure, retrying after dir reset: %v", err)
		os.RemoveAll(zshDir)
		err = shellutil.InitRcFiles(waveDataHome, binDir)
	}
	return err
}

When it happens

Trigger: Calling InitRcFiles (directly or via initCustomShellStartupFilesInternal / InstallRcFiles) when the destination file <waveHome>/zsh-integrations/.zlogin cannot be created or written: parent dir missing/deleted, insufficient permissions, immutable file, or template execution failure.

Common situations: Wave's cached config dir owned by root or another user after a sudo run; ~/.waveterm placed on a read-only or full disk; antivirus/EDR locking files on Windows; the zsh-integrations directory deleted while the app runs.

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

• error writing zsh-integration .zshenv: %v
• error writing zsh-integration .zprofile: %v
• error writing zsh-integration .zshrc: %v
• error writing bash-integration .bashrc: %v
• error writing bash-integration bash_preexec.sh: %v

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