Session registry client is required for rehydration (auth ma

Error message

Session registry client is required for rehydration (auth may be missing or registry is disabled)

What it means

rehydrate_session_in_worktree requires a session registry client to fetch the stored session record; when the Option is None it raises this error. This happens when auth was not provided or the registry is disabled, so there is no client to query the session's registry entry.

Source

Thrown at crates/codegen/xai-grok-shell/src/session/worktree.rs:517

            use xai_fast_worktree::{
                CreationMode, IgnoredFilesMode, WorkingTreeMode, WorktreeBuilder,
            };
            let mut builder = WorktreeBuilder::new(&source, &dest)
                .working_tree_mode(WorkingTreeMode::CleanAll)
                .ignored_files_mode(IgnoredFilesMode::Skip)
                .creation_mode(CreationMode::Linked)
                .worktree_kind(xai_fast_worktree::WorktreeKind::Fork)
                .session_id(session_id);
            if let Some(delegate) = btrfs_delegate {
                builder = builder.btrfs_delegate(delegate);
            }
            builder.create()
        })
        .await
        .map_err(|e| anyhow::anyhow!("worktree creation task failed: {e}"))??;
    }
    let client = registry_client.ok_or_else(|| {
        anyhow::anyhow!(
            "Session registry client is required for rehydration \
             (auth may be missing or registry is disabled)"
        )
    })?;
    let record = client
        .get_session(&req.session_id)
        .await
        .context("fetching session record for rehydration")?;
    let turn = crate::session::restore::resolve_restore_turn(&record, None);
    let memory_dl_future = crate::session::restore::download_to_tempfile(
        client,
        &req.session_id,
        "memory.tar.gz",
        turn,
    );
    let state_dl_future = async {
        Err(anyhow::anyhow!(
            "session-state archive restore unavailable in this build"

View on GitHub (pinned to bc7f02eddd)

Solutions

Ensure valid auth is configured so a registry client can be constructed before calling rehydrate.
Enable the session registry feature in configuration if it is disabled.
Check the code path that builds registry_client and log why it is None (auth missing vs disabled).
If registry is intentionally unavailable, use the local resume path (resume_local_session_in_worktree) instead of rehydration.

Example fix

// before
let client = registry_client.ok_or_else(|| anyhow!("Session registry client is required for rehydration..."))?;
// after — construct a client when auth is present
let client = match registry_client {
    Some(c) => c,
    None => build_registry_client(auth_manager.as_ref()).await.ok_or_else(|| anyhow!("..."))?,
};

Defensive patterns

Strategy: validation

Validate before calling

let client = build_registry_client(auth.as_ref()).await
    .ok_or_else(|| anyhow!("registry unavailable: configure auth or enable session registry before rehydrating"))?;
if !registry_enabled() { return Err(anyhow!("session registry disabled")); }

Type guard

fn has_registry_client(r: &Option<RegistryClient>) -> bool { r.is_some() }

Try / catch

match rehydrate_session_in_worktree(req).await {
    Err(e) if e.to_string().contains("registry client is required") => {
        // fall back to local resume which does not need the registry
        resume_local_session_in_worktree(req).await
    }
    other => other,
}

Prevention

Check auth/registry configuration at startup, not at rehydrate time
Fail fast with a clear preflight check before spawning worktrees
Provide a local-resume fallback when the registry is disabled
Log why registry_client was None (auth missing vs disabled)

When it happens

Trigger: Calling rehydrate_session_in_worktree with registry_client = None — i.e. no auth manager produced a registry client, or session registry support is disabled in configuration.

Common situations: Running rehydration headless/offline without credentials; deployment where the session registry feature flag is turned off; auth initialization silently failed.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/cddda2ab1749de07. Report an issue: GitHub.