[Bug]: Git storage sync fails with treeFolderDuplicate during asset adoption when directory matches existing path

[k0d3K]

Description

When using the Git storage target in Wiki.js v3, initiating a synchronization (syncStorageTargets) fails when importing media assets stored in subdirectories that share path segments or collide with existing page/documentation nodes.

During Assets.adoptStoredFile, the backend attempts to create parent folders in the database tree using Tree.createFolder. If a folder node or page entry already exists in wiki.tree for that path segment, Tree.createFolder throws an unhandled treeFolderDuplicate fatal error instead of fetching the existing node ID. This aborts the entire synchronization process and leaves the page tree and storage state inconsistent.

---

Steps to Reproduce

1. Set up Wiki.js v3 with PostgreSQL (default wiki schema) and configure a Git storage target.
2. In the Git repository, structure content where assets are nested inside documentation directories or sub-folders sharing path segments:

   procedures/
   ├── facturation.md
   └── facturation/
       ├── subpage.md
       └── img/
           └── screenshot.png
   

3. Trigger a storage synchronization via Administration > Storage > Force Sync or allow the background job syncStorageTargets to run.
4. Observe the job logs and failure.

---

Expected Behavior

Storage synchronization should be idempotent. If a folder or tree node already exists at a given path in wiki.tree, Tree.createFolder (or Assets.adoptStoredFile) should gracefully retrieve the existing folder ID (getOrCreate pattern) and continue adopting assets without throwing a fatal exception.

---

Actual Behavior

The sync job fails and rolls back with the following stack trace:

warn: treeFolderDuplicate: A folder with this path name already exists.
    at Tree.createFolder (file:///wiki/backend/models/tree.ts:886:13)
    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)
    at async Tree.addEntry (file:///wiki/backend/models/tree.ts:2259:11)
    at async Assets.adoptStoredFile (file:///wiki/backend/models/assets.ts:1228:19)
    at async adoptTree (file:///wiki/backend/helpers/storageFiles.ts:675:21)
    at async applyIncoming (file:///wiki/backend/modules/storage/git/storage.ts:1497:19)
    at async publish (file:///wiki/backend/modules/storage/git/storage.ts:1396:19)

---

Root Cause Analysis

1. Lack of Idempotency: Storage sync operations process incoming repository files incrementally. When processing nested assets (img/screenshot.png), intermediate parent directories must be ensured in the database.
2. Strict Uniqueness in Tree.createFolder: Tree.createFolder attempts to insert a new folder entry without first querying whether a node with the same folderPath and fileName already exists.
3. Path Collisions: When a page (facturation.md) and a folder (facturation/) share the same path segment name, Tree.createFolder encounters an existing record and throws treeFolderDuplicate, halting the entire sync pipeline.

---

Applied Fix

In /wiki/backend/models/tree.ts within Tree.createFolder, update the duplicate check to implement a getOrCreate pattern for folder nodes:

    const existing = await WIKI.db
      .select({ id: treeTable.id, type: treeTable.type })
      .from(treeTable)
      .where(
        and(
          eq(treeTable.siteId, siteId),
          eq(treeTable.locale, effectiveLocale),
          eq(treeTable.folderPath, path),
          eq(treeTable.fileName, name),
          ne(treeTable.type, 'page')
        )
      )
      .limit(1)
    if (existing.length > 0) {
      if (existing[0].type === 'folder') {
        return ((await this.getFolderById(existing[0].id)) ?? existing[0]) as TreeRow
      }
      throw new CustomError(
        'treeFolderDuplicate',
        existing[0].type === 'folder'
          ? 'A folder with this path name already exists.'
          : 'A file with this path name already exists here.',
        409
      )
    }

Verification & Result

• Tested and applied on my Wiki.js v3 instance.
• The container successfully restarted and storage synchronization is now fully idempotent, successfully reusing existing folder nodes without throwing fatal treeFolderDuplicate exceptions.

Helped by Gemini.

[NGPixel]

Fixed via e213715. Will land in next release.

However, your suggested fix actually makes things silently worst, as it doesn't address the actual mismatch between the input and what's already there.