Skip to content

fix(webdav): correct X-NC-WebDAV-Auto-Mkcol header name in docs #15422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SomSamantray wants to merge 2 commits into
base: master
Choose a base branch
from
Open

fix(webdav): correct X-NC-WebDAV-Auto-Mkcol header name in docs #15422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea9de91
docs(ce-work): checkpoint selected implementation plan
SomSamantray Aug 7, 2026
bb63a78
fix(webdav): correct X-NC-WebDAV-Auto-Mkcol header name in docs
SomSamantray Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 39 additions & 39 deletions developer_manual/client_apis/WebDAV/basic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ The table below summarizes common WebDAV methods used by Nextcloud and the most
+------------+-------------------------------------------+----------------------------------------------+-------------------------------------------------------------+
| PUT | ``/remote.php/dav/files/{user}/file`` | Optional: ``X-OC-MTime``, ``X-OC-CTime``, | Uploads/overwrites file content. |
| | | ``OC-Checksum``, ``OC-Total-Length``, | |
| | | ``X-NC-WebDAV-AutoMkcol`` | |
| | | ``X-NC-WebDAV-Auto-Mkcol`` | |
+------------+-------------------------------------------+----------------------------------------------+-------------------------------------------------------------+
| MKCOL | ``/remote.php/dav/files/{user}/folder`` | (none required) | Creates a folder. |
+------------+-------------------------------------------+----------------------------------------------+-------------------------------------------------------------+
Expand Down Expand Up @@ -583,44 +583,44 @@ Request Headers

You can set some special headers that Nextcloud will interpret.

+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| Header | Description | Example |
+=======================+=================================================================+============================================+
| X-OC-MTime | | Allow to specify a modification time. | ``1675789581`` |
| | | The response will contain the header ``X-OC-MTime: accepted`` | |
| | | if the mtime was accepted. | |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` |
| | | The response will contain the header ``X-OC-CTime: accepted`` | |
| | | if the mtime was accepted. | |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| OC-Checksum | | A checksum that will be stored in the DB. | ``md5:04c36b75222cd9fd47f2607333029106`` |
| | | For regular ``PUT`` uploads, the server stores the value | |
| | | without validation. During bulk uploads, the checksum | |
| | | **is** validated against the uploaded content. | |
| | | Currently used algorithms are ``MD5``, ``SHA1``, ``SHA256``, | |
| | | ``SHA3-256``, ``Adler32``. | |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| X-Hash | | On ``PUT`` requests, instructs the server to compute a hash | ``md5``, ``sha1``, ``sha256``, |
| | | of the uploaded file content during the write. The server | or ``all`` |
| | | returns the hash(es) in response headers named | |
| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, and/or ``X-Hash-SHA256``. | |
| | | Setting the value to ``all`` computes all three hashes. | |
| | | Beware of performance implications! | |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` |
| | | This allow the server to abort faster if the remaining | |
| | | user's quota is not enough. | |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| X-NC-WebDAV-AutoMkcol | | When set to ``1``, instructs the server to automatically | |
| | | create any missing parent directories when uploading a file. | |
| | | Available since Nextcloud 32. | |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
| OC-Chunked | | Used for legacy chunk upload to differentiate a regular | Deprecated |
| | | upload from a chunked upload. It allowed checking for quota | |
| (deprecated) | | and various other things. Nowadays, you need to provide the | You do not have to provide |
| | | ``OC-Total-Length`` header on the ``PUT`` requests instead. | this anymore |
+-----------------------+-----------------------------------------------------------------+--------------------------------------------+
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| Header | Description | Example |
+========================+=================================================================+============================================+
| X-OC-MTime | | Allow to specify a modification time. | ``1675789581`` |
| | | The response will contain the header ``X-OC-MTime: accepted`` | |
| | | if the mtime was accepted. | |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` |
| | | The response will contain the header ``X-OC-CTime: accepted`` | |
| | | if the mtime was accepted. | |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| OC-Checksum | | A checksum that will be stored in the DB. | ``md5:04c36b75222cd9fd47f2607333029106`` |
| | | For regular ``PUT`` uploads, the server stores the value | |
| | | without validation. During bulk uploads, the checksum | |
| | | **is** validated against the uploaded content. | |
| | | Currently used algorithms are ``MD5``, ``SHA1``, ``SHA256``, | |
| | | ``SHA3-256``, ``Adler32``. | |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| X-Hash | | On ``PUT`` requests, instructs the server to compute a hash | ``md5``, ``sha1``, ``sha256``, |
| | | of the uploaded file content during the write. The server | or ``all`` |
| | | returns the hash(es) in response headers named | |
| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, and/or ``X-Hash-SHA256``. | |
| | | Setting the value to ``all`` computes all three hashes. | |
| | | Beware of performance implications! | |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` |
| | | This allow the server to abort faster if the remaining | |
| | | user's quota is not enough. | |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| X-NC-WebDAV-Auto-Mkcol | | When set to ``1``, instructs the server to automatically | |
| | | create any missing parent directories when uploading a file. | |
| | | Available since Nextcloud 32. | |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+
| OC-Chunked | | Used for legacy chunk upload to differentiate a regular | Deprecated |
| | | upload from a chunked upload. It allowed checking for quota | |
| (deprecated) | | and various other things. Nowadays, you need to provide the | You do not have to provide |
| | | ``OC-Total-Length`` header on the ``PUT`` requests instead. | this anymore |
+------------------------+-----------------------------------------------------------------+--------------------------------------------+

Response Headers
----------------
Expand Down
89 changes: 89 additions & 0 deletions docs/plans/15365-fix-webdav-automkcol-header.md
View file
Open in desktop

@susnux susnux Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not think this should be committed ;)

Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
title: Fix X-NC-WebDAV-AutoMkcol header name in WebDAV client API docs
date: 2026-08-07
artifact_contract: ce-unified-plan/v1
artifact_readiness: implementation-ready
execution: code
product_contract_source: ce-plan-bootstrap
origin: issue #15365 (https://github.com/nextcloud/documentation/issues/15365)
depth: lightweight
settled_decision_conflicts: []
---

# Fix X-NC-WebDAV-AutoMkcol header name in WebDAV client API docs

## Problem Frame

The developer manual documents the optional upload header as
`X-NC-WebDAV-AutoMkcol` in `developer_manual/client_apis/WebDAV/basic.rst`
at two places (lines 111 and 615). The Nextcloud server reads
`X-NC-WebDAV-Auto-Mkcol` (with a second hyphen) in
`apps/dav/lib/Upload/UploadAutoMkcolPlugin.php` (line 41 of nextcloud/server
master). Clients following the documentation send the wrong header and
receive a 403 on uploads that should auto-create parent directories.

## Requirements

- R1. Rename the header from `X-NC-WebDAV-AutoMkcol` to
`X-NC-WebDAV-Auto-Mkcol` in both occurrences in
`developer_manual/client_apis/WebDAV/basic.rst`.
- R2. No other file in the repository may contain the misspelled
`AutoMkcol` variant after the change (verified by repository-wide grep).
- R3. The fix is documentation-only; no source code of this repository
changes, and no server-side behavior is proposed or requested.

## Scope Boundary

In scope: the two header-name occurrences in `basic.rst`.

Out of scope:
- Any change to server code (the server name is canonical).
- Reformatting or rewording the affected tables beyond the header name.
- Other documented headers or WebDAV endpoint behavior.

## Key Technical Decisions

- KTD-1 (user-directed): use `X-NC-WebDAV-Auto-Mkcol` as the corrected name.
Rejected alternative: keeping `AutoMkcol` — the server's
`UploadAutoMkcolPlugin` checks `X-NC-WebDAV-Auto-Mkcol`; the docs are
wrong, not the server. Evidence: nextcloud/server
`apps/dav/lib/Upload/UploadAutoMkcolPlugin.php:41`.

## Assumptions

- The server-side header name remains stable for the current and upcoming
documented versions (the plugin line was verified on server master).
- The reporter's observed 403 was caused by the header mismatch; the fix
aligns docs with server behavior.

## Implementation Units

### U-1 Rename header in WebDAV request-headers table

Files: `developer_manual/client_apis/WebDAV/basic.rst`

- Line 111 (PUT row in the request-methods table): replace
``X-NC-WebDAV-AutoMkcol`` with ``X-NC-WebDAV-Auto-Mkcol`` inside the
existing literal markup, keeping the table cell width intact.
- Line 615 (request-headers table row): replace the header cell
``X-NC-WebDAV-AutoMkcol`` with ``X-NC-WebDAV-Auto-Mkcol`` and widen the
first table column to fit the longer name, keeping the RST grid-table
borders aligned (re-run `sphinx-build`/`rst-lint` equivalent check or
visually verify the table renders).

Verification:
1. Repository-wide grep for `AutoMkcol` (excluding the hyphenated variant)
returns zero matches.
2. Grep confirms both `X-NC-WebDAV-Auto-Mkcol` occurrences exist at the
expected lines.
3. RST table structure remains valid (grid-table column widths consistent;
doc build succeeds or cell borders line up).

## Dependencies and Sequencing

Single unit; no ordering constraints.

## Risks

- RST grid tables break silently when column widths are edited
incorrectly — mitigation is the table-validity check in U-1 verification.