What causes "Could not get app cache dir" in gitbutlerapp/gitbutler?

Export HOME (or XDG_CACHE_HOME) to a writable path before running

Could not get app cache dir

Error message

Could not get app cache dir

What it means

Thrown by `app_cache_dir_for_channel` when `dirs::cache_dir()` returns None, so the platform cache directory cannot be determined and `<cache>/<channel-identifier>` cannot be built. On Linux this requires XDG_CACHE_HOME or HOME; without either, the function raises this error.

Solutions

Export HOME (or XDG_CACHE_HOME) to a writable path before running
In containers, define ENV HOME=... at image build time
Ensure the target cache directory's parent exists and is writable
In tests, set E2E_TEST_APP_DATA_DIR to bypass platform resolution

Example fix

// before
$ docker run image but ...   // no HOME

// after
$ docker run -e HOME=/home/user image but ...

Defensive patterns

Strategy: try-catch

Validate before calling

if std::env::var_os("HOME").is_none()
    && std::env::var_os("XDG_CACHE_HOME").is_none()
    && std::env::var_os("E2E_TEST_APP_DATA_DIR").is_none()
{
    eprintln!("Set HOME or XDG_CACHE_HOME before running");
}

Try / catch

match app_cache_dir() {
    Err(e) if e.to_string().contains("app cache dir") => {
        eprintln!("Cannot resolve cache dir: set HOME/XDG_CACHE_HOME");
    }
    r => r?,
}

Prevention

Define HOME in container images (ENV HOME=/home/user)
Set XDG_CACHE_HOME for services with sanitized environments
Ensure the cache parent directory exists and is writable
Use E2E_TEST_APP_DATA_DIR override in tests

When it happens

Trigger: Calling `app_cache_dir_for_channel(channel)` (directly or via `app_cache_dir`) when `dirs::cache_dir()` yields None — no XDG_CACHE_HOME and no resolvable HOME; E2E_TEST_APP_DATA_DIR not set.

Common situations: Minimal Docker images without HOME; systemd/cron services with empty environments; CI runners executing the app with a sanitized env; chroots lacking /home.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/4c5fe70dd5932c41. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-path/src/lib.rs:151

/// the compile-time or explicit channel.
///
/// # Errors
///
/// Returns an error if the platform's cache directory cannot be determined.
pub fn app_cache_dir() -> anyhow::Result<PathBuf> {
    app_cache_dir_for_channel(AppChannel::new())
}

/// Like [`app_cache_dir()`], but explicitly for `channel`.
///
/// When `E2E_TEST_APP_DATA_DIR` is set, `channel` is ignored and the result is always
/// `<E2E_TEST_APP_DATA_DIR>/cache`.
pub fn app_cache_dir_for_channel(channel: AppChannel) -> anyhow::Result<PathBuf> {
    if let Some(test_dir) = std::env::var_os("E2E_TEST_APP_DATA_DIR") {
        return Ok(PathBuf::from(test_dir).join("cache"));
    }
    dirs::cache_dir()
        .ok_or(anyhow::anyhow!("Could not get app cache dir"))
        .map(|dir| dir.join(identifier_for_channel(channel)))
}

/// Returns the bundle identifier for the compile-time [`AppChannel`].
pub fn identifier() -> &'static str {
    identifier_for_channel(AppChannel::new())
}

/// Returns the bundle identifier used for `channel`.
pub const fn identifier_for_channel(channel: AppChannel) -> &'static str {
    match channel {
        AppChannel::Nightly => "com.gitbutler.app.nightly",
        AppChannel::Release => "com.gitbutler.app",
        AppChannel::Dev => "com.gitbutler.app.dev",
    }
}

/// A way to learn about the currently configured compile-time app-channel.

View on GitHub (pinned to 58e5313667)