wavetermdev/waveterm · error

failed to read waveapps directory: %w

Error message

failed to read waveapps directory: %w

What it means

ListAllApps reads the ~/waveapps root directory to enumerate namespaces. If os.ReadDir on that root fails for any reason other than it not existing (which is handled as an empty list), the error is wrapped as "failed to read waveapps directory". This signals filesystem-level trouble with the waveapps root itself.

Source

Thrown at pkg/waveappstore/waveappstore.go:468

	if _, err := os.Stat(appDir); os.IsNotExist(err) {
		return nil, fmt.Errorf("app directory does not exist: %s", appDir)
	}

	return fileutil.ReadDirRecursive(appDir, 10000)
}

func ListAllApps() ([]wshrpc.AppInfo, error) {
	homeDir := wavebase.GetHomeDir()
	waveappsDir := filepath.Join(homeDir, "waveapps")

	if _, err := os.Stat(waveappsDir); os.IsNotExist(err) {
		return []wshrpc.AppInfo{}, nil
	}

	namespaces, err := os.ReadDir(waveappsDir)
	if err != nil {
		return nil, fmt.Errorf("failed to read waveapps directory: %w", err)
	}

	var appInfos []wshrpc.AppInfo

	for _, ns := range namespaces {
		if !ns.IsDir() {
			continue
		}

		namespace := ns.Name()
		nsPath := filepath.Join(waveappsDir, namespace)

		apps, err := os.ReadDir(nsPath)
		if err != nil {
			continue
		}

		for _, app := range apps {

View on GitHub (pinned to a4447c1563)

Solutions

1. Check permissions on ~/waveapps (user needs read + execute): ls -ld ~/waveapps
2. Confirm ~/waveapps is a real directory, not a file or broken symlink; recreate if needed
3. Fix ownership: chown -R "$USER" ~/waveapps
4. If it is on an external mount, remount the volume and retry

Example fix

// shell diagnosis
ls -ld ~/waveapps
// fix
sudo chown "$USER" ~/waveapps && chmod 755 ~/waveapps

waveappsDir := filepath.Join(homeDir, "waveapps")
if fi, err := os.Stat(waveappsDir); err == nil && (!fi.IsDir() || unix.Access(waveappsDir, unix.R_OK) != nil) {
	return fmt.Errorf("waveapps dir missing, not a directory, or unreadable: %s", waveappsDir)
}

apps, err := ListAllApps()
if err != nil {
	if strings.Contains(err.Error(), "failed to read waveapps directory") {
		return fmt.Errorf("cannot access ~/waveapps: %w (check permissions/symlink)", err)
	}
	return err
}

When it happens

Trigger: os.ReadDir(waveappsDir) fails with EACCES (no read permission on ~/waveapps), ELOOP (waveapps is a symlink loop), or an I/O error on a mounted volume — anything except a clean 'does not exist'.

Common situations: ~/waveapps created by another user or root with restrictive permissions; waveapps replaced by a file or broken symlink; network/external drive hosting waveapps that got disconnected mid-listing.

Related errors

• failed to create backup directory: %w
• failed to create socket directory: %w
• failed to create log directory: %w
• failed to open log file: %w
• failed to read directory: %w

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