wavetermdev/waveterm · error

failed to expand path: %w

Error message

failed to expand path: %w

What it means

verifyReadTextFileInput calls wavebase.ExpandHomeDir on the filename to resolve ~ and validate the path; if that function errors, the failure is wrapped as "failed to expand path". This is a pre-flight validation step before any file is opened.

Source

Thrown at pkg/aiusechat/tools_readfile.go:208

		return true, reason
	}

	if baseName == ".git-credentials" {
		return true, "Git credentials file"
	}

	return false, ""
}

func verifyReadTextFileInput(input any, toolUseData *uctypes.UIMessageDataToolUse) error {
	params, err := parseReadTextFileInput(input)
	if err != nil {
		return err
	}

	expandedPath, err := wavebase.ExpandHomeDir(params.Filename)
	if err != nil {
		return fmt.Errorf("failed to expand path: %w", err)
	}

	if !filepath.IsAbs(expandedPath) {
		return fmt.Errorf("path must be absolute, got relative path: %s", params.Filename)
	}

	if blocked, reason := isBlockedFile(expandedPath); blocked {
		return fmt.Errorf("access denied: potentially sensitive file: %s", reason)
	}

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

	if fileInfo.IsDir() {
		return fmt.Errorf("path is a directory, cannot be read with the read_text_file tool. use the read_dir tool if available to read directories")
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Use a plain absolute path ("/home/user/file.txt") instead of a tilde form.
2. Verify the home directory referenced by ~ exists and HOME/USERPROFILE resolves.
3. Inspect the wrapped %w cause for the underlying ExpandHomeDir failure.

Example fix

// before
{"filename": "~nonexistentuser/data.txt"}
// after
{"filename": "/home/realuser/data.txt"}

// prefer plain absolute paths to avoid expansion entirely
if strings.HasPrefix(p, "~") { /* ensure user exists / HOME is set */ }

if err := verifyReadTextFileInput(params); err != nil {
    if strings.HasPrefix(err.Error(), "failed to expand path") {
        // fall back to absolute path form and retry
    }
}

When it happens

Trigger: Passing a malformed path that ExpandHomeDir cannot process (e.g. invalid ~ expansion form like "~nonexistentuser/..." depending on home-dir resolution failing).

Common situations: Tilde paths referencing users that don't exist on this machine; corrupted HOME environment; paths containing platform-invalid constructs caught during expansion.

Related errors

• getting absolute path: %w
• resolving image path: %v
• path is a directory, not an image file
• getting absolute path: %w
• getting absolute path of parent dir: %w

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