{"record":{"id":"c0d5513eb1f6ec92","repo":"wavetermdev/waveterm","slug":"error-writing-zsh-integration-zshrc-v","errorCode":null,"errorMessage":"error writing zsh-integration .zshrc: %v","messagePattern":"error writing zsh-integration \\.zshrc: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/util/shellutil/shellutil.go","lineNumber":399,"sourceCode":"\tif runtime.GOOS == \"windows\" {\n\t\tpathSep = \";\"\n\t} else {\n\t\tpathSep = \":\"\n\t}\n\tparams := map[string]string{\n\t\t\"WSHBINDIR\":      HardQuote(absWshBinDir),\n\t\t\"WSHBINDIR_PWSH\": HardQuotePowerShell(absWshBinDir),\n\t\t\"PATHSEP\":        pathSep,\n\t}\n\n\t// write files to directory\n\terr = utilfn.WriteTemplateToFile(filepath.Join(zshDir, \".zprofile\"), ZshStartup_Zprofile, params)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error writing zsh-integration .zprofile: %v\", err)\n\t}\n\terr = utilfn.WriteTemplateToFile(filepath.Join(zshDir, \".zshrc\"), ZshStartup_Zshrc, params)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error writing zsh-integration .zshrc: %v\", err)\n\t}\n\terr = utilfn.WriteTemplateToFile(filepath.Join(zshDir, \".zlogin\"), ZshStartup_Zlogin, params)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error writing zsh-integration .zlogin: %v\", err)\n\t}\n\terr = utilfn.WriteTemplateToFile(filepath.Join(zshDir, \".zshenv\"), ZshStartup_Zshenv, params)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error writing zsh-integration .zshenv: %v\", err)\n\t}\n\terr = utilfn.WriteTemplateToFile(filepath.Join(bashDir, \".bashrc\"), BashStartup_Bashrc, params)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error writing bash-integration .bashrc: %v\", err)\n\t}\n\terr = os.WriteFile(filepath.Join(bashDir, \"bash_preexec.sh\"), []byte(BashStartup_Preexec), 0644)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error writing bash-integration bash_preexec.sh: %v\", err)\n\t}\n\terr = utilfn.WriteTemplateToFile(filepath.Join(fishDir, \"wave.fish\"), FishStartup_Wavefish, params)","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/util/shellutil/shellutil.go#L381-L417","documentation":"InitRcFiles renders ZshStartup_Zshrc via WriteTemplateToFile into <dir>/.zshrc; failure is wrapped in this error. Missing .zshrc means the main zsh integration hooks (prompt, commands, ssh integration) never load.","triggerScenarios":"InitRcFiles failing to write .zshrc after .zprofile succeeded — permissions changed mid-sequence, an existing .zshrc owned by another user/open, disk filling up between writes, or template execution error in ZshStartup_Zshrc params.","commonSituations":"User-owned dotfile directories where the app (running as another user) cannot overwrite; immutable or symlinked .zshrc pointing to a read-only target; SELinux/AppArmor denials on writing to HOME; quota exhaustion.","solutions":["Check the wrapped %v error to identify the exact OS-level cause","Ensure the .zshrc path is writable and not a symlink into a read-only location (or replace the symlink)","Free disk space / raise quota if ENOSPC","Align file ownership: chown the zsh integration directory to the user running the shell"],"exampleFix":"// before\nerr := shellutil.InitRcFiles(zshDir)\n// after\nif err := shellutil.InitRcFiles(zshDir); err != nil {\n\tvar pathErr *os.PathError\n\tif errors.As(err, &pathErr) && pathErr.Path != \"\" {\n\t\t_ = os.Chmod(zshDir, 0o700)\n\t}\n\treturn fmt.Errorf(\"failed to install zsh integration: %w\", err)\n}","handlingStrategy":"fallback","validationCode":"rcPath := filepath.Join(zshDir, \".zshrc\")\nif fi, err := os.Lstat(rcPath); err == nil && fi.Mode()&os.ModeSymlink != 0 {\n\t// symlinked rc file; ensure target writable or remove symlink\n}\nerr := shellutil.InitRcFiles(zshDir)","typeGuard":null,"tryCatchPattern":"if err := shellutil.InitRcFiles(zshDir); err != nil {\n\tif strings.Contains(err.Error(), \".zshrc\") {\n\t\treturn fmt.Errorf(\"cannot write zsh integration .zshrc into %s: %w\", zshDir, err)\n\t}\n\treturn err\n}","preventionTips":["Check for symlinked .zshrc files pointing to read-only targets","Ensure no immutable bits or ACLs block writes in the integration dir","Run shell integration setup as the owning user, not root","Handle partial installs: .zprofile may succeed while .zshrc fails — clean up or retry idempotently"],"tags":["zsh","file-write","shell-integration"],"backgroundTag":"rc-file-write-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}