Queue
Find the change holding up a school's queue, and retry or skip it.
An agent applies its queue front to back and stops at the first change it cannot write. It does not acknowledge past that change, so the next cycle tries the same one again, and everything queued behind it waits. That is deliberate — skipping a failure silently would lose the change — but a failure that will never succeed holds the whole direction up until someone deals with it.
The Queue tab on a school shows where each direction has got to and what is in the way.
Reading a direction
There is one card per direction, named for the changes it carries and the database they are written to:
| Card | Written to | By |
|---|---|---|
| DOWN changes | The local database | The local agent |
| UP changes | The online database | The online agent |
| Status | Meaning |
|---|---|
| Up to date | Nothing is waiting |
| N waiting | Changes are queued and nothing has failed; the next cycle applies them |
| Stalled · N waiting | The change at the front has failed at least once |
A stalled card shows the change at the front — table, row and operation — with the error the agent last reported, when it first failed and how many times it has been tried. Show row data opens the payload, which is usually where the cause is visible: a value too long for the column, a parent id that does not exist on this side, a duplicate of a unique value. Below it are the next changes waiting behind.
Typical causes:
- A missing parent. The child arrived before its parent, or the parent was never synced.
- A unique value already taken by a different row on the receiving side, such as an email address or an ID number.
- The two schemas differ — a column that is longer,
NOT NULL, or missing on one side. The Schema tab shows which. - The table does not exist on the receiving database.
Retry now
Fix the cause on the receiving database first, then press Retry now. The agent that writes this direction starts a cycle instead of waiting out its interval.
A resident agent (--watch) starts within a few seconds. One run by a scheduler has no way
to be woken, so it retries on its next scheduled start as it would have anyway. A request
that no agent picks up expires after ten minutes.
Skip
Skip… moves the queue past the change at the front, so the ones behind it can be applied on the next cycle. It is limited to administrators and asks for a reason.
A skipped change is lost
The change is never written to the other database, so that row differs between the two until it is edited again or backfilled. Prefer fixing the cause and retrying; skip only a change that genuinely should not land.
Only the change you were looking at is skipped. If the agent applied it, or the queue moved for any other reason, before you confirmed, nothing happens and the page asks you to look again.
Every skip is recorded:
- Under Skipped changes on the same tab, with the row data, the last error, the reason, and who skipped it.
- In sync history as a
SKIPPEDresult on the run the change belonged to. - In the agent logs for that side, as a warning.
Backfill the row
A skip leaves that one row different between the two databases. Once whatever made it fail is fixed — the duplicate email removed, the missing parent added — Backfill this row on the skipped change sends it again. Administrators only.
- The agent on the database the change came from reads the row as it is now, not the copy that was skipped, so edits made since are included.
- The row is staged for review exactly like a table backfill, and Review the row opens it. You see what it would change on the receiving side before approving.
- Once approved it is queued and applied like any other change.
The skipped change shows how it went: requested, ready for review, backfilled, rejected, or failed. If the row no longer exists on the source it says Not found and nothing is sent.
- Fix the cause first. The row goes through the queue again, and if the cause is still there it fails, and the queue stalls, exactly as before.
- It needs agent 1.2.0 or later on the source database. An older agent would read the request as "back-fill the whole table", so the server never hands it one, and the button says the agent needs updating.
- One backfill per table at a time. While a backfill of that table is open, whole or single row, another cannot be requested for it.