phacility/phabricator · error · Exception

Document path "%s" is not a valid path. The normalized form

Error message

Document path "%s" is not a valid path. The normalized form of this path is "%s".

What it means

PhrictionDocumentQuery's withPaths() and withAncestorPaths() require caller-supplied paths to already be in canonical normalized form. During query execution each path is compared against PhabricatorSlug::normalize(); any difference (case, trailing slash, spaces, missing leading slash) aborts the query, with the expected form echoed in the message. The strictness guarantees callers cannot silently query textual variants of one logical path.

Source

Thrown at src/applications/phriction/query/PhrictionDocumentQuery.php:272

      );

      $paths = array();
      foreach ($sets as $set) {
        $set_paths = $set['paths'];
        if ($set_paths === null) {
          continue;
        }

        if (!$set_paths) {
          throw new PhabricatorEmptyQueryException(
            pht('No parent/ancestor paths specified.'));
        }

        $is_parents = $set['parents'];
        foreach ($set_paths as $path) {
          $path_normal = PhabricatorSlug::normalize($path);
          if ($path !== $path_normal) {
            throw new Exception(
              pht(
                'Document path "%s" is not a valid path. The normalized '.
                'form of this path is "%s".',
                $path,
                $path_normal));
          }

          $depth = PhabricatorSlug::getDepth($path_normal);
          if ($is_parents) {
            $min_depth = $depth + 1;
            $max_depth = $depth + 1;
          } else {
            $min_depth = $depth + 1;
            $max_depth = null;
          }

          $paths[] = array(
            $path_normal,

View on GitHub (pinned to 5720a38cfe)

Solutions

Wrap every path in PhabricatorSlug::normalize() before adding it to the query
Use the normalized form printed in the exception message as the canonical value to store and pass
Centralize path construction in one helper that always normalizes

Example fix

// before: raw path passed straight into the query
$docs = id(new PhrictionDocumentQuery())
  ->setViewer($viewer)
  ->withPaths(array($path))
  ->execute();

// after: normalize before querying
$docs = id(new PhrictionDocumentQuery())
  ->setViewer($viewer)
  ->withPaths(array(PhabricatorSlug::normalize($path)))
  ->execute();

Defensive patterns

Strategy: type-guard

Validate before calling

$paths = array_map('PhabricatorSlug::normalize', $paths);
$docs = id(new PhrictionDocumentQuery())
  ->setViewer($viewer)
  ->withPaths($paths)
  ->execute();

Type guard

function isNormalizedPhrictionSlug($slug) {
  return is_string($slug) && $slug === PhabricatorSlug::normalize($slug);
}

// assert(all($paths, 'isNormalizedPhrictionSlug')) before withPaths()

Prevention

Normalize at the boundary: the moment a path enters your code, not at query time
Store only normalized slugs in your own tables and link metadata
Add the type guard to test suites that exercise phriction queries

When it happens

Trigger: Passing raw user input or hand-built path strings to PhrictionDocumentQuery::withPaths()/withAncestorPaths() without normalizing first; paths assembled with string concatenation or copied from external URLs.

Common situations: Custom applications embedding Phriction searches; wiki paths imported from external tools with different casing rules (e.g. MediaWiki); templates that render paths differently from how they store them.

Related errors

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