The Post You Wrote Offline Shows Up Twice — Designing a Send Outbox That Survives Retries

Put the box in SQLite so it survives a force quit

Fixing the key is pointless if the box itself vanishes when the app restarts. Not an in-memory array or component state, but somewhere that lives across a cold start — I use SQLite. MMKV persists too, but once the count grows, the querying and transactions of a write path are easier to handle in SQLite.

// outbox/store.ts
import * as SQLite from 'expo-sqlite';
 
const db = SQLite.openDatabaseSync('outbox.db');
 
db.execSync(`
  CREATE TABLE IF NOT EXISTS outbox (
    localId TEXT PRIMARY KEY,
    idempotencyKey TEXT NOT NULL,
    endpoint TEXT NOT NULL,
    payload TEXT NOT NULL,
    status TEXT NOT NULL,
    attempts INTEGER NOT NULL,
    nextAttemptAt INTEGER NOT NULL,
    dependsOn TEXT,
    createdAt INTEGER NOT NULL
  );
`);
 
export function insertItem(item: OutboxItem): void {
  db.runSync(
    `INSERT INTO outbox VALUES (?,?,?,?,?,?,?,?,?)`,
    item.localId, item.idempotencyKey, item.endpoint,
    JSON.stringify(item.payload), item.status, item.attempts,
    item.nextAttemptAt, item.dependsOn ?? null, item.createdAt,
  );
}
 
export function dueItems(now: number): OutboxItem[] {
  const rows = db.getAllSync<any>(
    `SELECT * FROM outbox
     WHERE status IN ('pending','failed') AND nextAttemptAt <= ?
     ORDER BY createdAt ASC`, now,
  );
  return rows.map((r) => ({ ...r, payload: JSON.parse(r.payload) }));
}

This foundation overlaps with the usual offline articles, so I'll keep it brief and move on. What matters is how you design ordering and failure handling on top of this box.

When a child write hangs off a parent you made offline

After duplicates, the next headache is dependencies. Say you "create an album" and then "add a photo to it" while offline. The album only has a device-local temporary ID (local:abc). Send the photo first and the server references a parent that doesn't exist — error.

There are two moves. First, give the child mutation a dependsOn so it won't send until the parent succeeds. Second, when the parent's send succeeds and the server ID comes back, remap the temporary ID inside the child's payload to the real one.

// outbox/remap.ts
// Called when a parent send succeeds. Propagates tempId -> serverId across the queue.
export function remapId(tempId: string, serverId: string): void {
  const children = db.getAllSync<any>(
    `SELECT * FROM outbox WHERE payload LIKE ?`, `%${tempId}%`,
  );
  for (const row of children) {
    // Walk the payload and replace tempId with serverId
    const replaced = JSON.parse(
      JSON.stringify(JSON.parse(row.payload as string))
        .split(tempId).join(serverId),
    );
    db.runSync(
      `UPDATE outbox SET payload = ?, dependsOn = NULL WHERE localId = ?`,
      JSON.stringify(replaced), row.localId,
    );
  }
}

Clearing dependsOn to NULL unblocks the child so it can send. The string replace looks crude, but if you mint temporary IDs with a non-colliding prefix like local:, accidental hits essentially never happen. Once I committed to that prefix rule, almost all of my remap bugs disappeared.

Don't let a write that can never succeed jam the front of the queue

This last part pays off the most in production. Suppose a mutation always returns 422 from server-side validation — a reply to someone already deleted, or an old payload made invalid by a spec change. Drop it into a "failed, so retry" loop and it jams the head of the queue forever, dragging every healthy write behind it down with it.

So split failures in two: ones a retry might fix (connection drops, 5xx, 429) and ones no number of retries will fix (most 4xx). The latter falls to quarantine (dead), and you tell the user quietly.

// outbox/runner.ts
const MAX_ATTEMPTS = 6;
 
function isRetryable(status: number): boolean {
  return status === 0 || status === 429 || status >= 500;
}
 
async function flushOne(item: OutboxItem): Promise<void> {
  db.runSync(`UPDATE outbox SET status='inflight' WHERE localId=?`, item.localId);
  try {
    const res = await send(item);
    if (res.ok) {
      const body = await res.json();
      if (body.id && item.payload && (item.payload as any).localId) {
        remapId((item.payload as any).localId, body.id);
      }
      db.runSync(`DELETE FROM outbox WHERE localId=?`, item.localId);
      return;
    }
    if (!isRetryable(res.status)) {
      // never going to work -> quarantine and notify
      db.runSync(`UPDATE outbox SET status='dead' WHERE localId=?`, item.localId);
      notifyUserOfDeadItem(item);
      return;
    }
    throw new Error(`retryable ${res.status}`);
  } catch (e) {
    const attempts = item.attempts + 1;
    const status = attempts >= MAX_ATTEMPTS ? 'dead' : 'failed';
    const backoff = Math.min(2 ** attempts * 1000, 5 * 60 * 1000); // cap 5 min
    db.runSync(
      `UPDATE outbox SET status=?, attempts=?, nextAttemptAt=? WHERE localId=?`,
      status, attempts, Date.now() + backoff, item.localId,
    );
  }
}

The flush as a whole must never run twice at once. Concurrent runs put the same item inflight twice, and even with the idempotency key in place you just burn extra round trips. A simple run lock plus catching the reconnect event from @react-native-community/netinfo exactly once was enough for me.

// outbox/loop.ts
let running = false;
 
export async function flush(): Promise<void> {
  if (running) return;        // single-run lock
  running = true;
  try {
    const batch = dueItems(Date.now()).filter((i) => !i.dependsOn);
    for (const item of batch) {
      await flushOne(item);    // serial
    }
  } finally {
    running = false;
  }
}

Items still carrying a dependsOn are skipped this pass and picked up on the next flush, once the parent resolves. Order holds by createdAt ascending, with dependencies as the only exception sent later — those two rules together preserve the before-and-after of what the user did offline.

What goes in the outbox, and what doesn't

Not every write needs to go through this. The heavier it gets, the more fragile it becomes. Here's how I draw the line.

For a toggle like a like, just "replace any unsent write to the same target before enqueuing," and the wasted round trips drop noticeably. You only need idempotency keys for the things you actually put in the box.

What changed after I shipped it

Since switching to this design, "the post showed up twice" reviews have all but stopped on my apps with write paths. Surfacing quarantined items on screen made failures that used to vanish silently visible, which also gave me the thread to pull on to fix the stale payloads behind them.

If you own your server, idempotency keys can start from a single received-log row. Run just one path through it first — creating a post, the one that hurts most to lose. Add idempotency keys and temp-ID remapping to a persistent retry queue, and the write path goes remarkably quiet. I hope it's a useful next step if you're stuck on the same thing.