sinelaw/fresh · error

remote home directory unknown

Error message

remote home directory unknown

What it means

home_dir calls sys_info() and needs info.home; if the remote system info lacks a home directory (or the request failed) there is no reliable remote $HOME, so the adapter raises NotFound. The connect-time liveness gate normally guarantees sys_info was primed, so this indicates a remote that answered connect but reports no home.

Solutions

1. Ensure the remote agent reports a home directory in its info response; fix the remote account env (set $HOME) or update the agent.
2. Fall back to an explicit configured home/path in the editor settings instead of querying the remote.
3. Reconnect the remote session if it degraded after the connect-time prime_sys_info gate passed.

Example fix

// before
let home = remote_fs.home_dir()?;
// after
let home = remote_fs.home_dir().unwrap_or_else(|_| {
    eprintln!("remote home unknown; using configured default");
    PathBuf::from(config.default_remote_home.as_deref().unwrap_or("/tmp"))
});

let info = remote_fs.sys_info()?;
if info.home.is_none() { eprintln!("remote did not report a home directory"); }

fn remote_home_known(info: &SysInfo) -> bool { info.home.as_deref().map(|h| !h.is_empty()).unwrap_or(false) }

let home = remote_fs.home_dir().unwrap_or_else(|_| {
    config.remote_home.clone().unwrap_or_else(|| PathBuf::from("/tmp"))
});

When it happens

Trigger: Calling home_dir() on a RemoteFileSystem whose sys_info response had home: null/absent, or whose sys_info() call now fails (remote degraded after connect).

Common situations: Remotes with restricted accounts or unusual environments (containers/service accounts without $HOME), custom agents that omit the home field in info, or a remote connection that went stale after the priming handshake.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• ${built.error}
• could not open from container
• Cannot open file: remote connection lost
• Cannot save: remote connection lost
• Cannot open files from multiple remote hosts. First

AI-assisted analysis of sinelaw/fresh@67894ca546 (2026-09-13). Data as JSON: /api/errors/7c34a53a96f44307. Report an issue: GitHub.

Appendix: source

Thrown at crates/fresh-editor/src/services/remote/filesystem.rs:575

    }

    fn remote_channel_id(&self) -> Option<u64> {
        Some(self.channel.id())
    }

    fn remote_reconnect_notify(&self) -> Option<std::sync::Arc<tokio::sync::Notify>> {
        Some(self.channel.reconnect_notify())
    }

    fn home_dir(&self) -> io::Result<PathBuf> {
        // Served from the connect-time cache on the hot path (workspace
        // restore / file open / file explorer), so the editor thread doesn't
        // block; see `sys_info`. A remote that couldn't answer `info` never
        // gets this far — the connect-time liveness gate (`prime_sys_info`)
        // rejects it before the session is promoted.
        self.sys_info()
            .and_then(|info| info.home)
            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "remote home directory unknown"))
    }

    fn unique_temp_path(&self, dest_path: &Path) -> PathBuf {
        // Use the remote system's temp directory instead of hardcoding /tmp,
        // which doesn't exist on Windows remotes. Served from the connect-time
        // cache when primed (see `sys_info`); falls back to /tmp if the info
        // request fails (e.g. older agent without temp_dir support).
        let temp_dir = self
            .sys_info()
            .map(|i| i.temp_dir)
            .unwrap_or_else(|| PathBuf::from("/tmp"));
        let file_name = dest_path
            .file_name()
            .unwrap_or_else(|| std::ffi::OsStr::new("fresh-save"));
        let timestamp = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_nanos())
            .unwrap_or(0);

View on GitHub (pinned to 67894ca546)