The public Microsoft Graph contract does not guarantee atomic If-Match enforcement at deferred final commit for replacement of an existing OneDrive Personal item, so this workflow should not be enabled where silent overwrite prevention is mandatory.

What is—and is not—documented

• If-Match on createUploadSession is documented: if the supplied ETag does not match the item at that time, the request returns 412 Precondition Failed.^1^
• deferCommit: true postpones creation/publication until an explicit completion request.^1^
• The explicit-commit example says If-Match can be used and shows @microsoft.graph.sourceUrl containing the upload-session URL.^1^
• Graph defines 412 as a supplied precondition not matching the resource’s current state.^2^

However, the documentation does not state that:

1. The ETag supplied when creating the session is retained and automatically rechecked at commit.
2. The final If-Match is atomically evaluated against the existing destination file immediately before replacement.
3. A final 412 guarantees that no destination modification occurred.
4. These semantics constitute a OneDrive Personal-specific conditional-replacement contract.
5. Retrying after a lost final response provides exactly-once or non-overwrite behavior.

Consequently, the requested guarantees cannot be confirmed from the published contract.

Published request shapes

Session creation for an existing item is documented by item ID:

POST /v1.0/drives/{drive-id}/items/{item-id}/createUploadSession
Authorization: Bearer {token}
Content-Type: application/json
If-Match: "{original-etag}"

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

Upload each range to the returned preauthenticated uploadUrl. Do not send the Bearer [Token] to that URL:

PUT {uploadUrl}
Content-Length: {range-length}
Content-Range: bytes {start}-{end}/{total-length}

{binary bytes}

The published explicit-commit example is:

PUT /v1.0/me/drive/root:/{path-to-parent}
Authorization: Bearer {token}
Content-Type: application/json
If-Match: "{original-etag}"

{
  "name": "workbook.xlsx",
  "@microsoft.graph.conflictBehavior": "replace",
  "@microsoft.graph.sourceUrl": "{uploadUrl}"
}

This example must not be treated as a verified conditional replacement recipe. It addresses the parent path, leaving unclear whether If-Match is evaluated against the parent or destination file. An unresolved OneDrive documentation issue reports that the operation instead required the full destination file path, contrary to the published example.^3^

The reported—but not provider-confirmed—variant is:

PUT /v1.0/drives/{drive-id}/root:/{full-path-to-file}
Authorization: Bearer {token}
Content-Type: application/json
If-Match: "{original-etag}"

{
  "name": "workbook.xlsx",
  "@microsoft.graph.conflictBehavior": "replace",
  "@microsoft.graph.sourceUrl": "{uploadUrl}"
}

Because the endpoint is disputed and the precondition target is not defined precisely, neither form satisfies the requirement for a definitive supported contract.

Item ID versus path

Use item-ID addressing for operations on an existing file whenever the API supports it. An item ID persists when the item is renamed or moved; a path stops identifying that item after either operation.^4^

That stability does not resolve deferred commit: the documented final sourceUrl example does not provide an item-ID form for replacing the existing destination. A path could also resolve to a different item after delete-and-recreate. Therefore, no documented equivalence between ID- and path-based conditional commit can be asserted.

Handling a timeout or ambiguous commit result

Do not blindly repeat the commit with a refreshed ETag; that could authorize overwriting a concurrent update.

1. Query the destination by its original item ID.
2. Record the returned ID, ETag, cTag, size, modification information, and file hash if the response supplies one.
3. Query the upload-session URL to determine whether the session still exists and whether ranges remain. Graph documents this status request for resuming interrupted uploads.^1^
4. Classify the result as:
   • Definitely not committed: destination still has the original ETag and the session remains pending.
   • Observed destination changed: destination metadata/content differs, but authorship of that change is not proven.
   • Indeterminate: session disappeared, the item was replaced/recreated, or destination state cannot uniquely identify the submitted bytes.
5. For an indeterminate result, stop automated writes and require reconciliation or restart from a newly read destination version.

Even matching ID, size, ETag, or hash only observes current state; it cannot prove atomicity or distinguish this commit from an identical concurrent write.

Keep the production prohibition and open a Microsoft support case requesting confirmation for OneDrive Personal deferred replacement, including the exact commit URI, the resource against which If-Match is evaluated, no-write-on-412 behavior, and timeout retry semantics. Support may provide product guidance, but a written contractual guarantee is not assured.

References

1. driveItem: createUploadSession
2. Microsoft Graph error responses and resource types
3. #1615 Commiting an upload session requires PUT to file path, and not to path of the parent
4. Address resources in a drive on OneDrive