WOPI PutFile fails with 500 (uncaught TypeError from files_versions) leading to save failures and conflict hints

[juliusknorr]

Summary

On a production system (Nextcloud server 34, COOLWSD 25.04, richdocuments) saves from Collabora intermittently fail. Collabora reports a conflict on the file and then fails to save. Investigation shows two distinct but related symptoms:

1. Save failure (HTTP 500): A TypeError thrown inside the files_versions write hook during putContent() escapes WopiController::putFile() uncaught and returns a bare 500 {"message":"Error"} to Collabora.
2. Conflict hint: Collabora's own timestamp-based conflict detection raises documentconflict — partly as a downstream effect of the failed/retried saves, partly via the WOPI timestamp comparison.

Update — the 500 is a known nextcloud/server bug, already fixed on master: nextcloud/server#60842 "fix(files_versions): guard null path in event listeners" (milestone NC 35, merged 2026-06-11) guards the five callers of getPathForNode() from passing null downstream — it explicitly addresses this basicOperation(): Argument #2 ($path) must be of type string, null given in public-link/groupfolder scenarios. Backports are in flight, including stable34 (#61189), stable33 (#61188), stable32 (#61187), stable31 (#61329). The production version 34.0.0.11 predates the stable34 backport, which is why it still crashes. (An earlier, related but different null fix was #51609, NC 32.) The richdocuments-side hardening below is still worthwhile so a hook \Error no longer surfaces as an uncaught 500.

Logs

Nextcloud (richdocuments), on POST …/wopi/files/12049115_…/contents:

Uncaught error: OC\Files\View::basicOperation(): Argument #2 ($path) must be of type string, null given,
called in …/View.php on line 525 in file …/View.php line 1204

Previous (root) exception:

TypeError: OC\Files\View::basicOperation(): Argument #2 ($path) must be of type string, null given
#0 …/View.php(525): OC\Files\View->basicOperation()
#1 …/Filesystem.php(496): OC\Files\View->file_exists()
#2 …/apps/files_versions/lib/Storage.php(165): OC\Files\Filesystem::file_exists()
#3 …/apps/files_versions/lib/Listener/FileEventsListener.php(210): OCA\Files_Versions\Storage::store()
#4 …/apps/files_versions/lib/Listener/FileEventsListener.php(83): …->write_hook()
…
#15 …/apps/richdocuments/lib/Controller/WopiController.php(665): OC\Files\Node\File->putContent()
#16 …/apps/richdocuments/lib/Controller/WopiController.php(935): {closure …putFile():665}()
#17 …/apps/richdocuments/lib/Controller/WopiController.php(912): …->retryOperation()
#18 …/lib/private/Files/Lock/LockManager.php(73): {closure …wrappedFilesystemOperation():911}()
#19 …/apps/richdocuments/lib/Controller/WopiController.php(915): …->runInScope()
#20 …/apps/richdocuments/lib/Controller/WopiController.php(665): …->wrappedFilesystemOperation()
#21 …/lib/private/AppFramework/Http/Dispatcher.php(165): …->putFile()

COOLWSD (same docKey, note the two access tokens):

WOPI::PutFile … access_token=wrsr… : 500 (Internal Server Error) Internal Server Error: {"message":"Error"}
ERR  Unexpected response to WOPI::PutFile. Cannot upload file to WOPI storage … 500 …
ERR  Failed to upload docKey … Notifying client.
WOPI::PutFile … access_token=0C6W… : 200 (OK) OK: {"LastModifiedTime":"2026-06-16T12:21:56.000000Z"}
… After failing to upload […], the size on WOPI host matches our uploaded last uploaded size: 1804864 bytes.
  We will assume this is our last uploaded version and synchronize the timestamp …

The wrsr… token consistently returns 500; the 0C6W… token consistently returns 200 for the same document broker (docbroker_5f67).

Root cause of the 500

1. WopiController::putFile() calls $file->putContent($content) (lib/Controller/WopiController.php:663).
2. putContent fires the filesystem pre-write hook before writing.
3. files_versions listens: FileEventsListener::write_hook() computes $path = $this->getPathForNode($node) and passes it to Storage::store($path). On stable34 there is no null check; getPathForNode() can return null (e.g. public-link / groupfolder contexts). Storage::store() then runs Filesystem::file_exists($path) at Storage.php:165.
4. Filesystem::file_exists(null) → View::basicOperation(…, null) → TypeError.
5. A TypeError extends \Error, not \Exception, so the catch (\Exception $e) in putFile() (lib/Controller/WopiController.php:677) does not catch it. It escapes to the AppFramework dispatcher → generic 500 {"message":"Error"}. → fixed upstream by fix(files_versions): guard null path in event listeners server#60842.

Why it is per-token / intermittent

getPathForNode() resolves the node path against the current user, falling back to the owner. richdocuments sets setUserScope($wopi->getEditorUid()) / setFilesystemScope($wopi->getUserForFileAccess()) (lib/Controller/WopiController.php:633-634, :967-970) and fetches the node from getUserForFileAccess()'s folder. For a token where the editor context differs from the owner (guest/share/groupfolder editor — see Wopi::getUserForFileAccess(), lib/Db/Wopi.php:158), the path resolution can fail and return null. The owner's token resolves fine, which is why one token 500s and another succeeds.

The conflict hint

This is a separate Collabora mechanism (verified in CollaboraOnline/online.mirror, wsd/DocumentBroker.cpp). The user-visible conflict is handleDocumentConflict() → error: cmd=load kind=documentconflict, triggered in download() / CheckFileInfo handling when the storage LastModifiedTime differs from what Collabora recorded after its last save (and it is not mid-upload):

if (!_storageManager.getLastModifiedServerTimeString().empty() &&
    !fileInfo.getLastModifiedServerTimeString().empty() &&
    _storageManager.getLastModifiedServerTimeString() != fileInfo.getLastModifiedServerTimeString()) {
    // … "Document has been modified behind our back. Informing all clients" → handleDocumentConflict();
}

richdocuments returns LastModifiedTime as Helper::toISO8601($file->getMTime()) in both CheckFileInfo (lib/Controller/WopiController.php:196) and the PutFile response (:673). Reasons the timestamp can mismatch and trigger a conflict:

• The save failures themselves: the failing token's content is never written (it throws in the pre-write hook), while the retry on the other token succeeds and bumps mtime. The failing session then sees a changed mtime → conflict.
• richdocuments' own guard: putFile() returns 409 COOLStatusCode=1010 (COOL_STATUS_DOC_CHANGED) when X-COOL-WOPI-Timestamp ≠ toISO8601(getMTime()) (lib/Controller/WopiController.php:645-651).
• Second-precision timestamps: toISO8601() builds from integer seconds and always formats .000000 (lib/Helper.php:64-69, see its own TODO: Be more precise…). Sub-second/1-second drift is enough for a string mismatch.
• Another writer (other editor/session, sync client, server-side rewrite) or object/S3 storage mtime behavior changing mtime between save and CheckFileInfo.

Suggested fixes

1. Primary (nextcloud/server): done on master via #60842; ensure the stable34 backport (#61189) lands so deployments on 34.x get it. This is the real fix for the 500. -> [stable34] fix(files_versions): guard null path in event listeners server#61189 as backport
2. richdocuments hardening: widen the catch in WopiController::putFile() to \Throwable so an \Error from a hook is handled and logged with context instead of escaping as an uncaught 500. (Does not make the failing save succeed, but avoids the bare 500 and improves diagnostics.)
3. Optional: revisit Helper::toISO8601() second-only precision to reduce spurious timestamp-mismatch conflicts.

Environment

• Nextcloud server: 34.0.0.11
• COOLWSD: 25.04.8.3
• richdocuments: as deployed on cloud.nextcloud.com

[juliusknorr]

Can a 500 be wrongly assumed to be a conflict?

Collabora never maps HTTP 500 → "conflict" directly — a bare 500 is a save failure (retry / "could not be saved"). But a 500 can indirectly surface as a conflict, always via Collabora's metadata reconciliation rather than the status code.

After a failed upload Collabora issues a CheckFileInfo and compares the storage LastModifiedTime/size against what it last recorded (wsd/DocumentBroker.cpp):

• size/timestamp match → "assume this is our last uploaded version, synchronize the timestamp" → no conflict.
• size/timestamp differ → "Document has been modified behind our back" → handleDocumentConflict() → error: cmd=load kind=documentconflict.

So a 500 becomes a wrongly-assumed conflict whenever the storage metadata diverges from Collabora's recorded value for a reason that is not a genuine concurrent human edit:

1. Partial / post-write failure — bytes (and mtime) changed but we still report failure → next CheckFileInfo shows a newer mtime → false conflict. (Note: the files_versions TypeError fires in the pre-write hook, so the file is untouched — a conflict reported alongside that specific 500 is, by construction, spurious.)
2. Second-precision rounding — Helper::toISO8601() builds from integer seconds and always formats .000000, so a sub-second/1-second drift flips the string comparison.
3. Concurrent successful save advancing mtime while another token's save 500s (the multi-token race in the original logs). This one can be real and should not be suppressed.

Inverse mis-classification

richdocuments also returned HTTP 500 for a genuine lock conflict (LockedException → 500 "File locked"), so a real conflict was delivered as a generic server error. That is the opposite mistake and is addressed below.

Hardening implemented

PR #5771 (branch claude/relaxed-euler-j3p2z1) hardens the richdocuments side so a failed save never looks like an external change:

• putFile()/postFile() now catch (\Throwable) (not just \Exception) so a hook \Error such as the files_versions TypeError produces a controlled response + log instead of an uncaught 500.
• Snapshot the mtime before writing and log a distinct error if it changed despite a failed save (partial-write canary, case 1 above).
• LockedException → 409 Conflict instead of 500, so the client retries and a true lock is no longer mis-reported as a server error.

Not included (tracked as follow-up): tightening Helper::toISO8601() to sub-second precision (case 2), which needs validation against the Collabora client first.

The underlying 500 still requires the server-side fix to land in 34.x: nextcloud/server#60842 (stable34 backport #61189).

---

Generated by Claude Code