Failed to fetch base branch from '${remote}': ${err.message}

Error message

Failed to fetch base branch from '${remote}': ${err.message}. Check your network connection and remote configuration.

What it means

Any sync failure that is not clearly a permission, not-a-repo, or configured-branch problem is treated as a network/remote issue. Because creating a worktree from an unverified start point risks branching from the wrong commit, the sync failure is fatal and rethrown with a connectivity-oriented message.

Source

Thrown at packages/isolation/src/providers/worktree.ts:970

      const errorMessage = err.message.toLowerCase();

      // Fatal errors - throw to prevent confusing downstream failures
      if (err.code === 'EACCES' || errorMessage.includes('permission denied')) {
        throw new Error(
          `Permission denied accessing repository at ${repoPath}. ` +
            'Check file permissions and try again.'
        );
      } else if (errorMessage.includes('not a git repository')) {
        throw new Error(
          `${repoPath} is not a valid git repository. ` +
            'Ensure the workspace was cloned correctly.'
        );
      } else if (errorMessage.includes('configured base branch')) {
        // Configured branch errors are fatal - user needs to fix their config
        throw err;
      } else {
        // Network errors, timeouts — cannot guarantee correct start-point
        throw new Error(
          `Failed to fetch base branch from '${remote}': ${err.message}. ` +
            'Check your network connection and remote configuration.'
        );
      }
    }
  }

  /**
   * Copy git-ignored files to worktree based on repo config.
   * Returns `configLoadFailed: true` when no config was provided and the
   * internal fallback load of the config fails — so the caller can surface
   * a warning without blocking worktree creation.
   *
   * `.archon` used to be copied unconditionally, because it was the only way a
   * workflow's own commands and scripts could be seen from inside the worktree it
   * executed against. That is now handled by the run's own source capture
   * (`@archon/workflows` `workflow-source.ts`), which keeps the source outside the
   * target entirely. The implicit copy is gone because it was never scoped to

View on GitHub (pinned to 0773b97458)

Solutions

Confirm connectivity to the git host (`git ls-remote <remote>` or `ssh -T git@github.com`)
Fix authentication: refresh SSH keys/agent (`ssh-add`) or update stored HTTPS credentials
Verify the remote URL is correct (`git remote -v`) and the branch exists on it
Retry when the network is available — the sync is intentionally retried from scratch, never skipped

Example fix

# before
ssh -T git@github.com  # Permission denied (publickey)
# after
eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519 && ssh -T git@github.com

Defensive patterns

Strategy: retry

Validate before calling

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
export async function canReachRemote(repoPath: string, remote = 'origin'): Promise<boolean> {
  try { await execFileAsync('git', ['-C', repoPath, 'ls-remote', '--exit-code', remote], { timeout: 15000 }); return true; }
  catch { return false; }
}

Try / catch

try {
  const env = await provider.create(request);
} catch (e) {
  const msg = (e as Error).message;
  if (msg.startsWith('Failed to fetch base branch from')) {
    // retry with backoff once connectivity/auth is verified
    console.error('Network/remote problem; verify git ls-remote works, then retry.');
  }
  throw e;
}

Prevention

Preflight `git ls-remote <remote>` in CI before runs requiring worktrees
Keep SSH keys loaded (ssh-agent) and HTTPS credentials fresh
Run network-dependent jobs only with confirmed egress/VPN
Ensure the configured base branch exists on the remote

When it happens

Trigger: syncWorkspaceBeforeCreate's underlying `git fetch <remote> <branch>` fails with a network error, DNS failure, timeout, authentication prompt/credential error, or unknown remote — anything not matching the earlier classification branches.

Common situations: Offline laptop or CI without network egress; VPN required to reach the git host; expired SSH key/passphrase or cached credentials; remote renamed or deleted; firewall blocking port 22/443.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/431cfd867eaf95d2. Report an issue: GitHub.