> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write Path Concepts

> What the upload queue records, how the write endpoint authenticates and applies uploads, and what happens to a write that fails temporarily, is rejected, or blocks the upload queue.

These concepts apply whichever write path setup you use. In each one, the client SDK records your app's local writes in an upload queue and calls your `uploadData()` function to send them to your write endpoint. Your write endpoint applies them to your source database, and the PowerSync Service syncs the result back to the client. [Write Path Overview](https://docs.powersync.com/handling-writes/write-path/overview.md) walks through these steps.

## Write Operations

The client SDK records each change to a synced table in the upload queue as one of three operations:

| Operation | Recorded for | Contains |
| - | - | - |
| `PUT` | `INSERT` | The row `id` and the value of each non-null column. |
| `PATCH` | `UPDATE` | The row `id` and the value of each changed column. |
| `DELETE` | `DELETE` | The row `id`. |

The SDK groups the operations from one local database transaction into a transaction in the upload queue.

## Authenticating Writes

> [!WARNING]
>
> PowerSync does not authenticate or authorize writes. Your write endpoint is responsible for both.

If your auth provider issues JWTs, we recommend that your write endpoint verify the same JWT that your app sends to PowerSync. Your backend connector's `fetchCredentials()` already returns this token, so `uploadData()` can send it in the request's `Authorization` header. To verify the token:

1. Check the signature with your auth provider's keys, usually from its JWKS URL.
2. Check the issuer and expiry.
3. Accept the audience that your PowerSync instance is configured for. If your write endpoint already verifies tokens for a different audience, add this one to the accepted list.

The `sub` claim holds the user ID. Use it to decide which writes that user is allowed to make. See [Authentication](https://docs.powersync.com/configuration/auth/overview.md) for the audience and keys each provider uses.

## Applying Writes Before Responding

Your write endpoint must store each write in the source database before it responds. Don't put writes in a queue to process later. If your backend has to apply writes asynchronously, use [Custom Write Checkpoints](https://docs.powersync.com/handling-writes/custom-write-checkpoints.md).

After an upload, the client requests a write checkpoint. This checkpoint marks the source database position at that moment. The client then waits until it has synced data up to that checkpoint before it updates the local database with the synced data. If a write is not in the source database yet, the synced data does not include it, and the change disappears from the device. It appears again after the write reaches the source database and syncs. See [Consistency](https://docs.powersync.com/architecture/consistency.md).

## What Happens When a Write Fails

The SDK removes changes from the upload queue only when `uploadData()` calls `complete()` on them. If `uploadData()` throws an error or returns without calling `complete()`, the changes stay in the queue. The SDK calls `uploadData()` again after a delay. It keeps doing this while the sync stream is connected. For the retry delay and how the sync status reports upload errors, see [Error Handling](https://docs.powersync.com/configuration/app-backend/client-side-integration.md#error-handling).

> [!WARNING]
>
> The queue is ordered, so a change that stays at the front holds back every write behind it. No later writes from that device upload until the change leaves the queue.

When a write fails, your write endpoint and `uploadData()` decide between the following outcomes.

### Retryable Errors

A **retryable error** is a failure that is likely to succeed later without any change to the write, such as a network error, a timeout, or a database that is temporarily unavailable. `uploadData()` throws, and the SDK retries.

A retry sends the whole transaction or batch again, including changes that your write endpoint may already have applied. Make each write safe to repeat. For example, don't reject a create or delete only because an earlier attempt already applied it.

### Rejected Writes

A **rejected write** is a write that your write endpoint will never apply, for example because it fails validation. Your write endpoint tells `uploadData()` that it rejected the write, preferably with a 2xx response that includes the reason. `uploadData()` then marks the write complete, and the queue keeps moving.

The rejected change stays in the local database until the upload queue is empty and the client has synced. Then the local data is replaced with the state from your source database. See [How Changes Are Rolled Back](#how-changes-are-rolled-back).

To keep a record of rejected writes, your write endpoint can store each one in a **dead-letter queue**: a table or queue on your backend that you inspect later. If you apply a dead-lettered write later, newer writes from the same client may already be in your source database, so the writes are applied out of order.

To show the user why a write was rejected, return the reason in the 2xx response, or write it to a table that syncs back to the client. See [Custom Conflict Resolution](https://docs.powersync.com/handling-writes/custom-conflict-resolution.md) for examples.

To reject fewer writes, consider relaxing backend constraints that aren't strictly required. Accepting slightly inconsistent data can be better than discarding the user's change.

### Blocked Transactions

A **blocked transaction** is a failed transaction that stays in the upload queue and prevents later writes from uploading. A transaction becomes blocked when `uploadData()` throws, or returns without calling `complete()`, for a write that a retry can't fix, such as one that violates a constraint. Your `uploadData()` code decides how to handle each response, so this can happen with any status, 4xx or 5xx. If `uploadData()` throws, the sync status shows an `uploadError` on every attempt.

Your app may also keep a transaction blocked on purpose, for example when your write endpoint refuses a write because the user lacks a permission that an administrator can grant.

Your app needs a way to resolve a blocked transaction, such as showing the problem to the user. When the cause is fixed, the next retry succeeds. If the write should be dropped instead, `uploadData()` calls `complete()` on the transaction. The change is rolled back like a rejected write, so the user loses the changes they made in that transaction.

## How Changes Are Rolled Back

The client has no explicit rollback operation. Instead, the client SDK keeps a copy of the data as last synced from the source database, separate from local changes. When the upload queue is empty and the client has synced up to its latest write checkpoint, the SDK replaces the local data with that synced copy. As a result:

* A change that your write endpoint applied appears in the synced copy, so the local data stays the same.
* A change that your write endpoint applied in a modified form is replaced with the version from your source database.
* A change that your write endpoint rejected is not in the synced copy, so the local data returns to its last synced state.
* A change that a later write from another client overwrote is replaced with that other write.

Until then, the local database keeps the user's changes, so your app shows them while uploads are pending or the device is offline.

## Related Pages

* [Handling Update Conflicts](https://docs.powersync.com/handling-writes/handling-update-conflicts.md): what happens when two clients change the same row.
* [Custom Conflict Resolution](https://docs.powersync.com/handling-writes/custom-conflict-resolution.md): strategies for resolving conflicts in your write endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.