Fix a working copy that can't catch up

Fix a working copy that can't catch up, belongs to another instance, needs a newer server, was made by another build or has no room to open.

A working copy follows one instance through its event log. Devices explains what the copy holds and when it falls behind.

409 reach_changed

What your credential may read changed since the copy was built, such as by a narrowed key or an item moved to another type, so the copy can't resume.

Build the working copy again. When the copy falls behind explains when a copy starts over.

this working copy can no longer be kept current

The CLI's device commands report catchup_too_old, reach_changed and instance_changed this way, with the code copy_expired and exit code 4. Each call that sends what the copy holds first confirms the instance, so instance_changed can end any of them unsent. The message ends rebuild the copy from the server. Queued writes are kept.

A write that moves an item to another type, or an edge to another source, can change the device's reach: it reports reach_changed after sending the writes queued behind it.

Run marfa device hydrate again. Leave out of --type any type the credential no longer reads, or it's refused type_not_permitted. Until it finishes:

  • After catchup_too_old, marfa device status reports the copy stale, and it answers reads, marked stale, while the hydrate fills it in place. marfa device drain and marfa device catch-up keep answering copy_expired.
  • After instance_changed, the hydrate builds the copy from the new instance, and holds each waiting write blocked with the reason instance_changed, so none reaches that instance unasked. Check marfa device queue, then send those you want with marfa device release --reason instance_changed, or drop one with marfa device withdraw <id>.

marfa device hydrate --in-place-only gives the same error where it can't fill the copy in place, with the reason instance_changed, reach_changed, slice_changed or head_past_log. It changes nothing: run marfa device hydrate without the option.

If the instance refuses the credential or its reach meanwhile, the stale copy ends, keeping the queued writes: marfa device status reports it expired, and only marfa device hydrate without the option rebuilds it.

For a folder, run marfa folders push, which rebuilds the copy itself.

this working copy is not waiting to be filled again in place (not_stale)

marfa device hydrate --in-place-only fills only a copy whose cursor the instance's event log let go. This copy is whole, or was never built, and nothing changed.

Run marfa device catch-up to bring a whole copy up to date, or marfa device hydrate without the option to build it again.

wrong_server

Before it sends a credential or a write, a device checks that the address still answers as the copy's instance. Another instance answered, so the device refused and named both. Nothing was sent, and the copy and its queued writes are kept.

Point the device back at the copy's instance. To work with the other instance, open a new working copy for it.

An app on the Swift SDK gets wrongServer from its first call to the server, with the server the store belongs to in expected and the one that answered in got. A store given a new address of its own instance follows it without an error. To start again on the other instance, close the copy, show the person the writes that would be lost with WorkingCopy.unsentWrites(in:), and pass them to WorkingCopy.remove(store:confirming:), as A store the copy refuses describes.

wrong_schema: made by another build of the core

The message ends was made by another build of the core. A working copy is a file that one build of the core made, and a build with a different schema refuses to open it, even to read. The CLI exits with 4 and names the file. Nothing is deleted or changed. It happens after a move to a release that changed the working copy's tables, which the changelog names.

The message counts the writes in the file that the server hasn't taken: waiting, blocked, refused or dead. Only the build that made the file can send them.

  • None. Run marfa device hydrate to build a new copy.
  • Some. Open the file with the build that made it, run marfa device drain to send the writes, and marfa device discard any refused write you don't want. Then hydrate a new copy with the newer build. Keep the old file until then, because deleting it loses those writes.

A write of kind merge_metadata is a tag merge the server no longer takes: read its tags with marfa device queue, and add them with marfa items tags add.

An app on the Swift SDK opens a refused copy with ifRefused: .replace, which replaces it when it holds no unsent writes, or removes it, as Open a copy and A store the copy refuses describe. A folder replaces its own store the same way.

storage_full

The working copy's volume is full, so the copy didn't open, even to read. The CLI exits 3, and a Swift app gets storageFull. Free room and open it again.

A declared type is in unreplacedTypes

An app declared an app.* type that the instance holds in another definition, and the instance refused to replace it. The hydration finished, and the type stays as the instance holds it, so a write that relies on the new definition may be refused. A key without schema.write can add optional fields and change a label, but not make a field required or remove one.

Hydrate again with a credential that may change the type, or change the declaration to match what the instance holds. Declare types says what a hydration does with each declared type.

Covered in their guides

What you seeGuide
server_too_old: the server is older than 0.0.86, the oldest a device works with. The copy and its queue are keptUpgrade an instance
An event stream ends with catchup_too_old or cursor_aheadWhen the stream ends
A Swift app's copy is .staleFill the copy. A held updates() or changes() refills it by itself

On this page