Troubleshooting

Start with the symptom you can observe. A failed request, an unchanged screen and an unchanged stored document are different observations. Keep the draft and the submitted content while you investigate.

Symptom Start here
My publishing client cannot access the site Check the authoring connection
A public save is refused with 401 or 403 Check the exact permission
A fragment read returns the whole page, 404 or 416 Check the document and selector separately
A blog page opens, but reading its comments by selector returns 404 Check the composed route
A save returns 412 after someone else edits Review the newer server copy
A save failed or timed out and I do not know whether it worked Keep the submission and reconcile
A related-data example returns 422 Check the referenced key and uniqueness
An invalid WebDAV upload succeeds Check the write path
A value is unchanged, transformed differently, or its update returns 422 Compare the input, stored value and served view
The chart stops updating or shows old values Check its source table and observer

Before changing anything

Record the exact URL, request method, selector, response status and response body. For a conditional save, retain the If-Match value and the ETag from the read that supplied it. Record whether the request used the public application URL or the owner's WebDAV URL. Do not include an API key, cookie or authorization header in a shared report.

Use disposable content when reproducing a write. The examples below name the conditions under which each fix was checked; an HTTP status by itself does not establish the cause. Follow the linked guide for its complete fixture and prerequisites.

My publishing client cannot access the site

Check: Confirm that the client is using the site's WebDAV address and its authoring credential. A successful public page read does not test that connection. Compare OPTIONS responses on the same existing resource through both endpoints.

In the tested read-only public fixture, public OPTIONS returned HEAD, GET, OPTIONS and no DAV header. The authoring endpoint advertised DAV: 1, 2 and authoring methods including PROPFIND and PUT. An unauthenticated authoring GET returned 401; an authenticated authoring GET of the same file returned 200 and its stored HTML.

Fix and verify: Configure the publishing client with the site's WebDAV URL and its existing authorized credential, then read a known file through that connection. Confirm the returned content belongs to the intended site before uploading. Keep authoring credentials in the publishing client, outside application JavaScript.

If that authenticated read still fails, retain its status and redacted response for the site owner. These checks do not establish a fix for an expired key, the wrong account or a console sign-in problem. See WebDAV.

A public save is refused with 401 or 403

Check: Identify the exact resource, method and selector being written. Compare them with the intended authorization rule. Check the actual request result; an authoring upload succeeding does not show that a public visitor may perform the same write.

Fix and verify: For an operation that is intended to be allowed, have the application author correct the rule's scope. In the tested note fixture, a public PUT without a matching rule returned 401 and left storage unchanged. Adding a rule for only that note's path, the PUT method and #shopping-note allowed the update. A PUT to #other remained refused, and that other paragraph stayed unchanged.

Repeat both controls on disposable content: the intended edit must succeed and read back correctly; an out-of-scope edit must still fail. The test used an anonymous visitor and an explicitly public note. It does not establish signed-in-user or group behavior. Do not copy its public access choice onto private data or add a broad grant merely to silence an error.

A fragment read returns the whole page, 404 or 416

Check: Read the document without a selector first. In the tested ordinary-file case, an absent file returned 404. The existing note returned 200 and included both paragraphs. Inspect that HTML for the intended target's actual ID or selector.

Then distinguish a URL fragment from the HTTP selector request:

Request detail Result in the note fixture
GET /notes.html#shopping-note The URL fragment did not select server content; the response was the whole document.
GET /notes.html with Range: selector=#shopping-note 206 with the selected paragraph and Content-Range: selector #shopping-note.
GET /notes.html with Range: selector=#not-here 416 because that selector matched no target in this fixture.

Fix and verify: Use the correct document path and send the selector in the Range header. Check the status, returned range and body together. In this example, success means exactly the intended paragraph is present and the other paragraph is absent. The request uses selector=; the response uses selector followed by a space.

If the page is composed through a route rather than stored at that literal URL, use the next check. See GET.

A blog page opens, but its comment fragment returns 404

Check: Compare a whole-page GET with a selector GET of the same URL. The tested blog fixture used a parameterized page that included comments from another document. Its whole-page GET returned 200 with the comments, while its selector GET returned 404 because there was no stored document at that literal route URL.

Fix and verify: For the blog example's recovery step, read the whole served page without a Range header. Accept the expected HTML response, parse it into a detached template, and require exactly one expected comments list. The complete guide supplies this code. Display the comparison as text; do not insert the returned page or run its scripts.

The tested selector POST to that route updated the included source; a subsequent whole-page GET and an authoring read of the source both showed the new comment. That does not make the route's selector GET supported. If the recovery list is missing, duplicated, the wrong element, or the read fails, keep the pending submission and leave review incomplete.

A save returns 412 after another edit

Check: Compare the validator sent in If-Match with the ETag from a fresh read of the same source and selector. In the tested plain-note fixture, two edits started from one fragment validator. The first conditional PUT succeeded; the second used that old validator, returned 412 and did not overwrite the first edit.

Fix and verify: Keep your draft. Read the current server copy, compare it with your draft and explicitly reconcile the differences. Submit the reviewed result with the validator from that new read. Read back the accepted result. This sequence returned 206 and preserved the reviewed text in the test.

Do not remove If-Match or resend the old body with a fresh validator without reviewing the change. The complete fragment editor keeps a confirmed copy, an editable draft and a frozen pending request separately. Its example requires an ordinary uncomposed paragraph and a strong fragment validator; transformations and handlers require their own reconciliation checks.

A save failed or timed out; I do not know whether it worked

Check: Preserve the exact submitted body as well as any newer edits made while the request was pending. A missing usable response leaves the outcome unresolved; changing the display or enabling another save is not a recovery check.

Fix and verify: Use the linked editor's “Read server copy; keep draft” action and compare the returned source with the frozen submission and current draft. Complete the explicit review before another attempt. In the browser tests, a lost response kept both copies and blocked another save. A recovery read updated only the comparison copy. A 412, a wrong recovery target and edits typed while a save was pending also left the draft intact.

For an append such as a blog comment, use the blog recovery procedure. Its read did not resend the POST, execute returned scripts or replace the local comments list. A matching-looking comment alone does not uniquely identify which submission created it; do not use that comparison as an automatic retry decision.

Keep a copy of your draft and pending body before leaving the page. These examples provide in-page recovery, not a tested guarantee that drafts survive closing the tab. If the result cannot be reconciled, keep it unresolved and ask the application owner to inspect the write rather than blindly retrying.

Check: Read the response and compare the submitted values with the installed schema. In the Project/Task example, a Task's project value references the Project's unique slug; it is not a document URL. The declaration identifies both the target type and property: https://example.com/Project#slug.

Fix and verify: Save the intended Project first, then submit a Task with that Project's existing slug value. The tested matching pair was accepted, while a missing target key returned 422. A second Project with the same unique slug also returned 422 and created no resource. If you meant the existing Project, reference its existing key instead of creating a duplicate.

Read back the accepted resources. Keep failed submissions available for correction. These results apply to the configured application PUTs, not every possible cause of 422 or every inheritance, rename and deletion case. Do not bypass the refusal by uploading the invalid application record through WebDAV.

An invalid WebDAV upload succeeds

Check: Identify which endpoint accepted the write. In the tested relationship fixture, the application path rejected a missing reference with 422, while authenticated WebDAV authoring stored that missing value. In the transformation fixture, authoring retained mixed-case input that an application write normalized.

Fix and verify: Treat authoring as trusted file maintenance. When a workflow needs the application's rules, use its intended application write path with the required permissions, and test both an invalid submission and a valid one there. The related-data checks above provide a bounded example: missing target refused, matching target accepted and read back.

An accepted WebDAV upload is not evidence that application validation passed. Review authored content before relying on it in the app. See the WebDAV write-path contract for its broader authoring behavior. Do not treat a publishing credential as a substitute for application authorization.

A transformation does not produce the expected value

Check: Compare three things separately: the request body, stored HTML read through authoring, and the public served representation. Use the complete schema in Transforming data, including its Sessel/Lambda bindings.

For that fixture, the tested application HTML PUT of My-Project stored my-project; its public GET showed MY-PROJECT. An authoring upload kept its original mixed-case value. Those are different paths and representations.

Fix and verify: Match the example's application endpoint, method and HTML representation. For its required slug property, a plain-text selector PUT returned 422 and preserved the previous value. Sending the complete HTML span, including the property name, returned 206 and stored the normalized value. Read both stored and served forms to check the intended result.

Do not expect the write transform to repair otherwise invalid input before validation: the tested lowercase-only validator refused uppercase input before normalization. Trimming and lowercasing also left interior spaces and punctuation intact. If your requirements differ, establish and test the relevant validation and transformation contract before relying on it.

The chart stops updating or shows old values

Check: Inspect the readable source table first. If its values are correct but the chart is stale, compare the integration with the complete widget example. That example uses Chart.js 4.5.1 and watches the stable #sales-source container around #sales-data.

Fix and verify: Keep that parent container stable and use the example's full module. Test a value edit, row deletion and replacement of the table inside the container. All three updated the chart in Chrome. Invalid values, an empty table and a missing table cleared the chart's previous data; repairing or reinserting valid source data rebuilt it.

If the library is unavailable, the tested example leaves the table readable and reports the problem. Use that source view while investigating the library load. This integration derives a chart from the DOM; these checks do not establish server persistence or live delivery of remote changes. If the source table itself is stale, investigate the source read before changing the chart.

When these checks do not explain the result

Prepare a small reproduction with disposable content. Include the expected and observed result, time, public or authoring path, method, selector, relevant schema/rule, status, redacted response, and what a fresh read showed. State which proposed remedy you tried and whether it changed stored content or only the display. Preserve any unresolved draft separately.

The cases on this page were checked on November 6, 2026, using isolated hosted HTTP fixtures and Chrome runs of the linked examples. Browser failure tests used controlled responses; they establish the editor's recovery behavior, not the server outcome of a lost request. The hosted service did not expose its deployed revision. Different rules, representations, deployments or browsers need their own checks; a passing example is not whole-platform certification.