phacility/phabricator · error · DiffusionSetupException

The clone of this repository ("%s") on the local machine ("%

Error message

The clone of this repository ("%s") on the local machine ("%s") could not be read. Ensure that the repository is in a location where the web server has read permissions.

What it means

Before serving a repository, DiffusionRequest::validateWorkingCopy checks that the parent directory of the repository's local path is readable. If is_readable(dirname($path)) fails, raisePermissionException throws this DiffusionSetupException naming the repository and host: the web server or daemon user cannot even traverse the storage directory.

Source

Thrown at src/applications/diffusion/request/DiffusionRequest.php:552

  /**
   * Check that the working copy of the repository is present and readable.
   *
   * @param   string  Path to the working copy.
   */
  protected function validateWorkingCopy($path) {
    if (!is_readable(dirname($path))) {
      $this->raisePermissionException();
    }

    if (!Filesystem::pathExists($path)) {
      $this->raiseCloneException();
    }
  }

  protected function raisePermissionException() {
    $host = php_uname('n');
    throw new DiffusionSetupException(
      pht(
        'The clone of this repository ("%s") on the local machine ("%s") '.
        'could not be read. Ensure that the repository is in a '.
        'location where the web server has read permissions.',
        $this->getRepository()->getDisplayName(),
        $host));
  }

  protected function raiseCloneException() {
    $host = php_uname('n');
    throw new DiffusionSetupException(
      pht(
        'The working copy for this repository ("%s") has not been cloned yet '.
        'on this machine ("%s"). Make sure you have started the '.
        'daemons. If this problem persists for longer than a clone should '.
        'take, check the daemon logs (in the Daemon Console) to see if there '.
        'were errors cloning the repository. Consult the "Diffusion User '.
        'Guide" in the documentation for help setting up repositories.',

View on GitHub (pinned to 5720a38cfe)

Solutions

Identify the effective daemon and webserver users (bin/phd status, webserver config) and the local path (repository.default-local-path)
Fix ownership and permissions: chown -R <daemon-user> <repo-root> and chmod -R u+rwX,go+rX <repo-root>
Verify as the service user: sudo -u <webserver-user> ls -la <parent-dir>
On NFS, review mount options and root-squash behavior

Defensive patterns

Strategy: validation

Validate before calling

// Check storage readability before rendering the repository
$local_path = $repository->getLocalPath();
if (!is_readable(dirname($local_path))) {
  // show the setup/permissions guidance instead of hitting the exception
}

Try / catch

try {
  $request->validateRepository();
} catch (DiffusionSetupException $ex) {
  // Render the dedicated setup-error page with the remediation steps
  return $this->newDialog()->setTitle($ex->getMessage());
}

Prevention

Provision repository storage with ownership for the daemon/webserver users from day one
Verify readability as the service user after any storage migration
Monitor for DiffusionSetupException in logs as an early permissions tripwire

When it happens

Trigger: Browsing or serving a repository whose storage directory (or an ancestor of it) has permissions excluding the webserver/daemon user — for example a root-owned 0700 repository root created during setup.

Common situations: Storage root created by root with a restrictive umask; storage moved to a new mount; daemons running as a different user than expected; NFS root-squash hiding ownership.

Related errors

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/75c7ed622cfbf0bc. Report an issue: GitHub.