MyJackfruit

Help
Browse topics · For developers

For developers

← Back to Why was my write refused?

How do I write only if nothing changed (If-Match)?

Short answer

Read the record and keep its ETag, send PUT, PATCH or DELETE with If-Match set to it, and on 412 read it again.

Before you start

Your app can read and change a record at its /lws/r/<record id> address, as the answer on writing a record and reading it back shows.

Words used here (2)
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
record's address
A record's address is the web address that names one record for good: it never changes and is never given to another record.
Steps
  1. Read the record and keep its ETag.

    Send GET to the record's address and keep the ETag header of the answer.

    More about this

    An ETag is a fingerprint of the record's current state. You also get one from a create (201), a PUT and a PATCH, and as etag in each row of a listing asked for with include=body. The forms sha256:…, W/sha256:… and a listing's etag name the same state, and each is accepted in If-Match.

  2. Send the change with If-Match.

    Send PUT, PATCH or DELETE to the same address with the header If-Match: <the ETag>.

    More about this

    PUT needs it: without it the answer is 428 PreconditionRequired. On PATCH and DELETE it is optional, but without it your change lands even if someone changed the record after you read it; a DELETE without it can end a record another device just changed. If-Match: * matches any current state of a record that exists. A list of ETags is allowed; one match is enough.

  3. On 412, read again, merge and send again.

    A 412 PreconditionFailed answer means the record changed after you read it and nothing was written: GET it, put your change into the new version, and send it with the new ETag.

    More about this

    The message reads If-Match does not match the current ETag (stale write). Store the ETag of every answer you get, for the next change. Rarely, when another kind of write, such as an edit of a cell in a view, changes the record at the same moment, the 412 message reads Concurrent write detected (compare-and-swap conflict).; nothing was written, so do the same.

Deeper

Also asked:

How do I update a record without overwriting someone else's change? Send your PUT, PATCH or DELETE with If-Match set to the ETag you read. If someone changed the record since then, the answer is 412 and nothing is written: read it again and send your change once more.

What does 412 mean when I write? 412 PreconditionFailed means the record changed after you read it, so your If-Match no longer matches and nothing was written. Read it again, put your change into the new version and send it with the new ETag.

Only PUT, PATCH and DELETE at a record's /lws/r/<record id> address read If-Match. These ignore it: PUT /base/e/<record id> and POST /base/cell, the writes of a relation, PUT /base/r/<id> and POST /base/r/<id>/end, and DELETE /files/<id>, whose ETag is the hash of the file's bytes, not of its record. A vault's note takes its version in the body, not in If-Match, as the guide's chapter Dev.Guide.Writing shows.

If the record was ended after you read it, your ETag no longer matches and a PUT or PATCH with If-Match answers 412 (a DELETE answers 404); a PATCH sent without If-Match answers 409 EntityEndedError. Drop the change, or bring the record back with a PUT of all its facts and If-Match: *, which answers 201. A 412 or 428 does not tell you that you may write the record: PUT and PATCH compare If-Match before they check write access, so a caller who may not write can get 412 or 428 there, and 403 only with a matching tag. On DELETE, write access is checked first.

GilbApp sends If-Match with every PUT to a record at /lws/r/<record id> and with some PATCHes, such as the save of a person's card or a plan, but many of its edits, such as a field of most records, a process step or a sharing change, are sent without it. So a person's edit in GilbApp can land between your read and your write. That is what If-Match is for.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.Writing, https://appbuilder.gilb.com/base/e/06gkzpwmgnzph1fb6jp7gf87c0, and Dev.Guide.Sync, https://appbuilder.gilb.com/base/e/06gkzpwqkxz1h5002g87j1p3x0. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/lws/crud.ts:1-45 (the verbs; PUT If-Match required, PATCH and DELETE optional), :151-156 (etagFor sha256:<hex>), :300-312 (428 PUT requires an If-Match precondition (LWS conditional write).), :325-380 (comparison and write in one transaction; :371-377 CAS 412 Concurrent write detected (compare-and-swap conflict). from a writer that takes no lock), :388-397 (FOR UPDATE lock: two /lws writes meet as a stale 412), :403-430 (If-Match: * needs the record to exist; 412 If-Match does not match the current ETag (stale write). :427), :341-343 and :491-494 (If-Match compared before the write gate on PUT and PATCH), :432-528 (PATCH), :560-741 (DELETE, ⛔ No 428 when absent; write gate first :626-629, :684-688; 404 for an absent or ended record :642-657); src/lws/records.ts:175 (a listing row has etag only with include=body); src/http/entity-tag.ts:1-48 (a list; the platform's own tag with W/ matches, :14-47); src/lws/routes.ts:349-360 (428/412 bodies error + message), :998-1140, :1051-1058 (PATCH: 404 to a caller who may not read); the code at 498d29a0 shows/routes, src/lws, src/files: only src/lws/crud.ts and src/lws/routes.ts read it (so PUT /base/e/:id src/routes/write.ts, POST /base/cell, PUT /base/r/:id and POST /base/r/:id/end src/routes/relation.ts, DELETE /files/:id src/routes/files.ts:776-807 ignore it; the file ETag is the content hash, files.ts:947); src/lws/routes.ts:922-975 (the vault note: version in the body); src/write/errors.ts:55-72 (409 EntityEndedError); src/write/ingest.ts:1766-1780. GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/lib/base/records.ts:902-927 (replaceRecord sends if-match), :994-1046 (patchRecord: no If-Match by default); callers that send it: src/lib/base/recordHooks.ts:2271-2273 (person and organisation save), :2355-2356 (plan-record save), PlanFunctionForm.tsx:164-167, PlanStakeholders.tsx:100-103, PlanTagLinks.tsx:195-198 and :741-744, PlanDescriptionParts.tsx:551-555, valueChildRecords.ts:214-215, recordFactItems.ts:74, recordSidecarSave.ts:87; callers that do not: recordHooks.ts:2357 (other records), processHooks.ts:751 and :945 (process steps), entityShare.ts:509-512 (sharing), picture.ts:189-241, FileDetail.tsx:348. Dev.Guide.Writing (A 06gkzpwmgnzph1fb6jp7gf87c0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied); Dev.Guide.Sync (A 06gkzpwqkxz1h5002g87j1p3x0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied) Writing.ETag (all forms name the same state; weak accepted, verified 2026-10-15), .IfMatch (the table, 428 and 412 bodies), .VaultNote (version in the body, A header is ignored here), .Refusals (403 or 404, whatever If-Match for PUT and PATCH: the code differs, Guide fault G3; the page follows the code); Sync.SendChange, .SendDelete, .OnRefusal (412, 409 EntityEndedError, 404 on DELETE); Files.End (DELETE /files/<id> ignores If-Match). Note on report (standards): its claim that GilbApp's step save sends no If-Match holds (processHooks.ts:932-950 at ebd9415e, :945); the backend does accept If-Match on PATCH /lws/r/:id (crud.ts:432-528). The code example is written here, placeholders only. Row: Developer.ConditionalWrite.

For developers

TypeScript

change-safely.ts

// Change one fact without overwriting someone else's change: read, PATCH with If-Match, and on 412 read again.
// headersFor makes Authorization: DPoP <token> and a new DPoP proof for one method and address.
export async function setFact(
  recordUrl: string, // https://<name>.gilb.com/lws/r/<record id>
  fact: string, // such as "a:title"
  value: unknown,
  headersFor: (method: string, url: string) => Promise<Record<string, string>>,
): Promise<string> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const read = await fetch(recordUrl, { headers: await headersFor("GET", recordUrl) });
    if (read.status !== 200) throw new Error(`read answered ${read.status}`);
    const etag = read.headers.get("etag")!;
    const res = await fetch(recordUrl, {
      method: "PATCH",
      headers: {
        ...(await headersFor("PATCH", recordUrl)),
        "content-type": "application/merge-patch+json",
        "if-match": etag,
      },
      body: JSON.stringify({ [fact]: value }),
    });
    if (res.status === 200) return res.headers.get("etag")!; // keep it for the next change
    if (res.status !== 412) throw new Error(`change answered ${res.status}`);
    // 412: someone changed it after the read. Read again and send the change on the new version.
  }
  throw new Error("the record keeps changing: show the person the current version");
}

Checked against GilbApp d529620.