wavetermdev/waveterm · error

failed to expand path: %w

Error message

failed to expand path: %w

What it means

ReadDir first normalizes its input with wavebase.ExpandHomeDir (resolving ~/ and ~user/ prefixes); if that expansion itself errors, the failure is wrapped here. Expansion fails on malformed home-relative paths or when the user's home directory cannot be determined.

Source

Thrown at pkg/util/fileutil/readdir.go:41

	Mode         string `json:"mode"`
	Modified     string `json:"modified"`
	ModifiedTime string `json:"modified_time"`
}

type ReadDirResult struct {
	Path         string        `json:"path"`
	AbsolutePath string        `json:"absolute_path"`
	ParentDir    string        `json:"parent_dir,omitempty"`
	Entries      []DirEntryOut `json:"entries"`
	EntryCount   int           `json:"entry_count"`
	TotalEntries int           `json:"total_entries"`
	Truncated    bool          `json:"truncated,omitempty"`
}

func ReadDir(path string, maxEntries int) (*ReadDirResult, error) {
	expandedPath, err := wavebase.ExpandHomeDir(path)
	if err != nil {
		return nil, fmt.Errorf("failed to expand path: %w", err)
	}

	fileInfo, err := os.Stat(expandedPath)
	if err != nil {
		return nil, fmt.Errorf("failed to stat path: %w", err)
	}

	if !fileInfo.IsDir() {
		return nil, fmt.Errorf("path is not a directory")
	}

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

	totalEntries := len(entries)

View on GitHub (pinned to a4447c1563)

Solutions

1. Pass an absolute path instead of a ~-relative one.
2. Check the HOME environment variable is set for the process user (`echo $HOME`), or run via a login shell.
3. If using '~user' syntax, confirm that user exists in /etc/passwd on the host.
4. Call wavebase.ExpandHomeDir yourself first to see the precise underlying error.

Example fix

// before
fileutil.ReadDir("~/logs", 100)
// after
fileutil.ReadDir("/home/alice/logs", 100)

if strings.HasPrefix(path, "~") && os.Getenv("HOME") == "" {
	return fmt.Errorf("HOME is not set; pass an absolute path instead of %q", path)
}
abs, err := wavebase.ExpandHomeDir(path)
if err != nil { return err }

res, err := fileutil.ReadDir(path, max)
if err != nil && strings.Contains(err.Error(), "failed to expand path") {
	// fall back to the literal path or prompt the user for an absolute path
}

When it happens

Trigger: Calling ReadDir with a path like "~/x" or "~" where wavebase.ExpandHomeDir cannot resolve the home directory (e.g. HOME unset and no passwd entry for the current user, or a malformed '~user' with unknown user).

Common situations: Running inside a minimal container or service (systemd, cron) where HOME is not set; passing a literal path containing a stray '~'; a '~otheruser' path for a user that doesn't exist on the host.

Related errors

• failed to stat path: %w
• path is not a directory
• getting absolute path for %s: %w
• failed to get app directory: %w
• failed to get builder executable path: %w

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