wavetermdev/waveterm · error

failed to stat file: %w

Error message

failed to stat file: %w

What it means

Returned when os.Stat (or an equivalent filesystem stat call) fails for the target file, e.g. because it does not exist, permissions are insufficient, or a path component is not a directory. The underlying error is wrapped with %w.

Source

Thrown at pkg/util/fileutil/fileutil.go:341

			}
			results[i].Applied = false
			results[i].Error = "previous edit failed"
			continue
		}

		modifiedContents, results[i] = applyEdit(modifiedContents, edit, i)
		if !results[i].Applied {
			failed = true
		}
	}

	return modifiedContents, results
}

func ReplaceInFile(filePath string, edits []EditSpec) error {
	fileInfo, err := os.Stat(filePath)
	if err != nil {
		return fmt.Errorf("failed to stat file: %w", err)
	}

	if !fileInfo.Mode().IsRegular() {
		return fmt.Errorf("not a regular file: %s", filePath)
	}

	if fileInfo.Size() > MaxEditFileSize {
		return fmt.Errorf("file too large for editing: %d bytes (max: %d)", fileInfo.Size(), MaxEditFileSize)
	}

	contents, err := os.ReadFile(filePath)
	if err != nil {
		return fmt.Errorf("failed to read file: %w", err)
	}

	modifiedContents, err := ApplyEdits(contents, edits)
	if err != nil {
		return err

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the path exists (ls / os.Stat) and correct typos.
2. Resolve or remove dangling symlinks before editing.
3. Check directory permissions (execute bit on parent dirs) for the current user.
4. Create the file first if it may not exist, or skip editing when os.Stat returns NotExist.

Example fix

// before
err := fileutil.ReplaceInFile("/app/config.json", edits) // file missing

// after
if _, err := os.Stat(path); os.IsNotExist(err) {
    return fmt.Errorf("cannot replace in missing file %s", path)
}
err := fileutil.ReplaceInFile(path, edits)

func ensureEditableFile(path string) error {
    fi, err := os.Stat(path)
    if err != nil {
        return fmt.Errorf("cannot edit %s: %w", path, err)
    }
    if !fi.Mode().IsRegular() {
        return fmt.Errorf("%s is not a regular file", path)
    }
    return nil
}

// Go: distinguish not-exist from other stat failures
if err := fileutil.ReplaceInFile(path, edits); err != nil {
    if strings.Contains(err.Error(), "failed to stat file") {
        if _, serr := os.Stat(path); os.IsNotExist(serr) {
            // create the file or abort
        }
    }
}

When it happens

Trigger: Calling ReplaceInFile (directly or via editTextFileCallback / ReplaceInAppFile) with a path that does not exist, has a broken symlink, or whose parent directories deny traversal permission.

Common situations: Typo in the file path; editing a file that was deleted or moved; dangling symlink; running without permission on a protected path; case-sensitivity mismatches on Linux paths.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• failed to get app directory: %w
• failed to get builder executable path: %w
• build output not found: %w
• failed to read app manifest: %w
• failed to stat file for backup: %w

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