phacility/phabricator · error · PhabricatorFileStorageConfigurationException

Malformed local disk storage root. You must provide an absol

Error message

Malformed local disk storage root. You must provide an absolute path, and can not use '%s' as the root.

What it means

PhabricatorLocalDiskFileStorageEngine requires the storage.local-disk.path configuration to be a non-empty absolute path other than '/'. getLocalDiskFileStorageRoot() throws PhabricatorFileStorageConfigurationException when the config is missing, is literally '/', or does not start with '/' (a relative path). This is a setup/configuration failure raised the moment the local-disk engine tries to resolve a storage path.

Source

Thrown at src/applications/files/engine/PhabricatorLocalDiskFileStorageEngine.php:105

      Filesystem::remove($path);
    }
  }


/* -(  Internals  )---------------------------------------------------------- */


  /**
   * Get the configured local disk path for file storage.
   *
   * @return string Absolute path to somewhere that files can be stored.
   * @task internal
   */
  private function getLocalDiskFileStorageRoot() {
    $root = PhabricatorEnv::getEnvConfig('storage.local-disk.path');

    if (!$root || $root == '/' || $root[0] != '/') {
      throw new PhabricatorFileStorageConfigurationException(
        pht(
          "Malformed local disk storage root. You must provide an absolute ".
          "path, and can not use '%s' as the root.",
          '/'));
    }

    return rtrim($root, '/');
  }


  /**
   * Convert a handle into an absolute local disk path.
   *
   * @param string File data handle.
   * @return string Absolute path to the corresponding file.
   * @task internal
   */
  private function getLocalDiskFileStorageFullPath($handle) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Set an absolute path: ./bin/config set storage.local-disk.path /var/phabricator/files (or edit the config JSON directly)
Create the directory and make it writable by the web server and daemon users (mkdir -p /var/phabricator/files && chown www-data:www-data /var/phabricator/files)
Never use '/' or a relative path as the storage root

Example fix

// before (local.json)
"storage.local-disk.path": "files/data"

// after
"storage.local-disk.path": "/var/phabricator/files"

Defensive patterns

Strategy: validation

Validate before calling

$root = PhabricatorEnv::getEnvConfig('storage.local-disk.path');
if (!$root || $root === '/' || $root[0] !== '/') {
  // fail setup loudly before selecting the local-disk engine
}

Try / catch

catch PhabricatorFileStorageConfigurationException at storage-engine selection and render a setup/diagnostic error page instead of a runtime 500.

Prevention

Validate storage paths in deployment config before switching engines
Use absolute paths on mounted volumes in containerized setups
Confirm the directory exists and is writable by the web/daemon users before first upload

When it happens

Trigger: Selecting the local-disk storage engine while storage.local-disk.path is unset; setting it to a relative value like 'files/' or './data'; setting it to '/' as the root.

Common situations: Fresh installs copying trimmed example config; containerized deployments assuming a relative working directory; config applied in the wrong environment or overridden later with an empty value.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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