Permission denied accessing repository at ${repoPath}. Check

Error message

Permission denied accessing repository at ${repoPath}. Check file permissions and try again.

What it means

syncWorkspaceBeforeCreate wraps the workspace sync (fetch/reset against the base branch) and classifies failures. When the underlying git operation fails with EACCES or a 'permission denied' message, it rethrows a dedicated, human-readable permission error so the user fixes filesystem access before retrying rather than seeing a raw git failure.

Source

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

      // Only hard-reset for Archon-managed clones when creating isolated worktrees.
      // Locally-registered repos keep the non-destructive fast-forward mode.
      const isManagedClone = repoPath
        .replace(/\\/g, '/')
        .startsWith(getArchonWorkspacesPath().replace(/\\/g, '/'));
      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.'
        );
      }

View on GitHub (pinned to 0773b97458)

Solutions

Fix ownership: `chown -R $(whoami) <repoPath>` or align the user Archon runs as with the workspace owner
Restore read/write permissions on the repo directory: `chmod -R u+rw <repoPath>`
Check for root-owned `.git` lock files or objects and re-own them
If the workspace lives on a read-only mount, move the Archon workspace path to a writable location

Example fix

# before
ls -l .git/HEAD  # owned by root, mode 644
# after
sudo chown -R $(id -u):$(id -g) /path/to/repo && chmod -R u+rw /path/to/repo

Defensive patterns

Strategy: try-catch

Validate before calling

import { accessSync, constants } from 'node:fs';
export function assertRepoWritable(repoPath: string): void {
  accessSync(repoPath, constants.R_OK | constants.W_OK);
  accessSync(`${repoPath}/.git`, constants.R_OK | constants.W_OK);
}

Try / catch

try {
  const env = await provider.create(request);
} catch (e) {
  const msg = (e as Error).message;
  if (msg.startsWith('Permission denied accessing repository')) {
    console.error('Fix ownership/permissions on the repo and .git, then retry:', msg);
  }
  throw e;
}

Prevention

Run Archon as the same user that owns the workspace clone
Avoid cloning workspaces with sudo
Watch for root-owned `.git` lock files after runs with elevated privileges
Ensure the Archon workspace path is on a writable mount

When it happens

Trigger: WorktreeProvider.create → syncWorkspaceBeforeCreate where reading/writing the repo at repoPath fails with err.code 'EACCES' or a message containing 'permission denied' (e.g. during `git fetch`, object writes, or lock-file creation).

Common situations: Workspace cloned by root but Archon runs as another user; read-only mounts; SSH key or credential-file permissions causing git to report access denied; group-write restrictions on `.git` inside the workspace.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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