OneDrive Personal: supported deferred upload commit and atomic eTag protection for an existing item

Jens Meyerholz 0 Reputation points
2026-11-16T12:03:40.8466667+00:00

Hello Microsoft Graph team,

We are implementing safe synchronization for a desktop application using Microsoft Graph v1.0 and a personal OneDrive account. Our requirement is to update an existing file without overwriting another client's concurrent change, while retaining the same item ID. We also need to handle a lost or delayed final response safely.

Reproduction

We used new, synthetic files inside an isolated folder in the app's OneDrive app folder. For each test we:

  1. Created a file and verified its item ID, parent, name, size, hash and eTag E1.
  2. Created an update upload session for that item with If-Match: E1 and deferCommit: true.
  3. Sent the complete replacement content to the returned preauthenticated upload URL. The final fragment was accepted with HTTP 202.
  4. Sent a final Graph PUT containing @microsoft.graph.sourceUrl set to the upload URL, name, and @microsoft.graph.conflictBehavior: replace, with an If-Match header.

Using either the parent-ID-and-file-path form or the existing item-ID form with the file's eTag returned HTTP 400 invalidRequest, with a message classified as requiring a data URI. Adding an empty file facet did not change the outcome. Moving @microsoft.graph.conflictBehavior=replace from the JSON body into the URL also returned the same error for both forms. After each test we verified that the old item ID, parent, name, size and QuickXorHash were unchanged. These are observations for one account, not a general claim about the service.

Separately, sending the file eTag with a PUT addressed to the parent folder produced HTTP 412; using the parent's current eTag instead produced the same HTTP 400 data-URI error. We do not interpret the former as proof that the file's version was protected at commit.

Relevant documentation: createUploadSession, driveItem instance attributes, upload or replace contents.

Questions

  1. For an existing item in OneDrive Personal, what exact supported final request (method, URL, headers and JSON) commits a deferred session to that same item ID? Should @microsoft.graph.conflictBehavior be in the URL or body? What explains the data-URI error for the tested forms?
  2. Does If-Match on session creation remain an atomic precondition when the session is finally committed, or must the final request carry it? For the supported final request, precisely which item's eTag is compared, and is the comparison atomic with publication of the new content?
  3. What are the guaranteed outcomes if the target is concurrently modified, renamed, moved, deleted or recreated? Which status codes guarantee that the update was not published, and is the original item ID preserved on success?
  4. If the client loses the final response or disconnects, how can it prove a pending request can no longer publish later? Which session status, cancellation or expiration semantics provide a definitive outcome, including after a client restart?
  5. Is If-Match on PUT /me/drive/items/{item-id}/content officially supported as an atomic condition on the final content update? We observed 412 for stale eTags in limited tests, but the endpoint's documentation does not state this condition. Does the guarantee differ for OneDrive Personal, OneDrive for Business and SharePoint?

Please cite the applicable contract or documentation and distinguish documented guarantees from observed implementation behaviour. We can provide a fresh, sanitized reproduction and diagnostic request IDs privately if required.

Thank you.

Microsoft Security | Microsoft Graph
0 comments No comments

Answer accepted by question author

AI answer

2026-11-16T12:05:49.9066667+00:00

The public Microsoft Graph v1.0 contract does not document a OneDrive Personal deferred-commit operation that both targets an existing item by ID and atomically revalidates that item’s eTag at publication, so the tested flow cannot currently provide the synchronization guarantee you require.

Documented deferred completion request

For OneDrive Personal, the upload-session documentation says that after all ranges have been uploaded with deferCommit: true, completion uses a final metadata PUT; the zero-length POST alternative is supported only by OneDrive for Business and SharePoint. The documented PUT is addressed to the destination parent path, not to /items/{existing-item-id} or /content:^1^

PUT https://graph.microsoft.com/v1.0/me/drive/root:/{path_to_parent}
Authorization: Bearer {token}
Content-Type: application/json
If-Match: {etag-or-ctag}

{
  "name": "file.dat",
  "@microsoft.graph.conflictBehavior": "replace",
  "@microsoft.graph.sourceUrl": "{uploadUrl}"
}

The same page says @microsoft.graph.sourceUrl identifies the existing upload session and explicitly shows conflict behavior in the JSON body. However, the DriveItem instance-attribute page says conflict behavior should be placed in the URL rather than the body. It describes conflict behavior as applying to actions that create a new item, while sourceUrl instructs the service to fetch URL content during a PUT.^2^

That is a documentation inconsistency. Neither page publishes:

  • an equivalent final PUT addressed to /me/drive/items/{existing-item-id};
  • a schema requiring sourceUrl to be a data: URI;
  • a OneDrive Personal request guaranteed to replace that exact item while retaining its ID.

Consequently, the invalidRequest/data-URI response cannot be authoritatively explained from the published contract. Adding an empty file facet is not documented as part of this request and should not be relied upon. Your parent-path request most closely matches the example, but its failure requires service-side investigation rather than another payload variation.

eTag and atomicity boundaries

If-Match is explicitly documented for creating the upload session:

POST /me/drive/items/{item-id}/createUploadSession
If-Match: E1
Content-Type: application/json

{
  "deferCommit": true,
  "item": {
    "@microsoft.graph.conflictBehavior": "replace"
  }
}

A mismatch at that point returns 412 Precondition Failed.^1^

The documentation does not state that this precondition is retained and re-evaluated when a deferred session is committed. Although the explicit-commit example says If-Match can be used, it does not define:

  • whether the compared eTag belongs to the parent or an existing child;
  • whether the comparison and content publication are atomic;
  • whether a rename, move, delete, or delete-and-recreate invalidates publication;
  • whether successful replace preserves an existing item ID.

Your parent-folder result is consistent with the header being evaluated against the addressed resource: a file eTag yielded 412, while the parent eTag passed that check and reached later request validation. That remains observed behavior, not a documented child-item concurrency guarantee.

The DriveItem model distinguishes eTag—metadata plus content—from cTag, which represents content and does not change for metadata-only updates.^2^ No retrieved contract maps either tag to an atomic deferred publication check for an existing Personal item.

Therefore, no documented status-code matrix guarantees non-publication for every concurrent modification, rename, move, deletion, or recreation case. A 412 guarantees that the documented precondition failed for the request/resource on which it is supported; it does not establish which child version was protected by the parent-addressed commit.

Lost responses and session lifetime

Persist the opaque uploadUrl, expirationDateTime, target item ID, original eTag, expected size, and expected hash before uploading. After a disconnect or restart:

  1. Send GET {uploadUrl} to retrieve missing ranges and the current expiration time.
  2. If the session is still pending and publication must be prevented, send:
DELETE {uploadUrl}

A successful cancellation returns 204 No Content and cleans up the temporary uploaded data. Uncommitted fragments are discarded after session expiration, although temporary-file deletion might not occur immediately.^1^ Each uploaded fragment extends the expiration time, which is why the latest returned value—not only the initial value—must be persisted.^3^

The documentation does not define cancellation as a barrier against a commit request already in flight, nor does it provide an idempotency key or terminal “committed versus cancelled” receipt. After an ambiguous final response, reconcile both:

  • the session state through its upload URL; and
  • the target DriveItem by ID, comparing its eTag, size, and expected content hash.

That can establish observed final state, but the published API does not provide a proof that an already accepted delayed request can never publish later. If that proof is mandatory, deferred commit on OneDrive Personal is not a sufficient documented protocol.

Direct /content replacement

The documented direct replacement operation is:

PUT /me/drive/items/{item-id}/content
Authorization: Bearer {token}
Content-Type: application/octet-stream

<replacement bytes>

It supports files up to 250 MB and returns the updated DriveItem.^4^ Its request-header table does not list If-Match. Therefore, observed 412 responses with stale eTags are useful implementation evidence but are not a published atomic-concurrency guarantee for OneDrive Personal, OneDrive for Business, or SharePoint. No product-specific difference in that guarantee is documented on this endpoint.

For a contractual answer covering atomic publication, item-ID preservation, races, and ambiguous completion, open a Microsoft Graph support case and include the sanitized requests, timestamps, drive type, request IDs, client-request IDs, and responses. Ask support to confirm whether the behavior is supported or incidental and to reconcile the contradiction between the upload-session example and the DriveItem annotation guidance.


References

  1. driveItem: createUploadSession
  2. driveItem resource type
  3. uploadSession resource type
  4. Upload or replace the contents of a driveItem
AI-generated content may be incorrect. Read our transparency notes for more information.

Was this answer helpful?

1 person found this answer helpful.

0 additional answers

Sort by: Most helpful

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.