${repoPath} is not a valid git repository. Ensure the worksp

Error message

${repoPath} is not a valid git repository. Ensure the workspace was cloned correctly.

What it means

During pre-create workspace sync, an error whose message contains 'not a git repository' is translated into this dedicated error, because branching a worktree from a non-repo directory would produce meaningless results. It signals the workspace checkout itself is missing or broken.

Source

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

      const { branch } = await syncWorkspace(
        repoPath,
        configuredBaseBranch ? toBranchName(configuredBaseBranch) : undefined,
        { mode: isManagedClone ? 'reset' : 'fast-forward', remote }
      );
      getLog().debug({ repoPath, branch, remote }, 'workspace_synced');
      return branch;
    } catch (error) {
      const err = error as Error & { code?: string };
      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.

View on GitHub (pinned to 0773b97458)

Solutions

Verify repoPath contains a `.git` directory (`ls -a <repoPath>/.git`); if not, re-clone the workspace
Correct the repo path in your Archon configuration if it points to the wrong directory
Re-run the Archon workspace setup/clone step to rebuild a corrupted checkout
Check you didn't delete `.git` (e.g. an overzealous clean script) and restore it from the remote

Example fix

# before
/path/to/workspace  # no .git, only source files
# after
rm -rf /path/to/workspace && archon setup  # or: git clone <url> /path/to/workspace

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
export async function assertIsGitRepo(repoPath: string): Promise<void> {
  if (!existsSync(`${repoPath}/.git`)) {
    throw new Error(`${repoPath} has no .git; re-clone or fix the configured path`);
  }
  await execFileAsync('git', ['-C', repoPath, 'rev-parse', '--git-dir']);
}

Try / catch

try {
  const env = await provider.create(request);
} catch (e) {
  if ((e as Error).message.includes('is not a valid git repository')) {
    console.error('Re-clone the workspace or correct canonicalRepoPath before retrying.');
  }
  throw e;
}

Prevention

Verify the workspace exists and has `.git` before pointing Archon at it
Point config at the repo root, not a subdirectory
Avoid cleanup scripts that delete `.git`
Re-run workspace setup after any interrupted clone

When it happens

Trigger: syncWorkspaceBeforeCreate (via WorktreeProvider.create) invokes git in repoPath and git exits with 'fatal: not a git repository (or any of the parent directories)'.

Common situations: The recorded workspace path points at a deleted or renamed directory; a clone failed or was interrupted leaving no `.git`; the configured canonicalRepoPath points at a subdirectory instead of the repo root; `.git` was removed accidentally.

Related errors

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