Folders

A folder keeps its own working copy and its record of which file is which item. Sync a folder sets one up.

A folder refuses to open with unknown field searchCopy anchor link

The message names an unknown field, search. The folder's system.folder item still holds search, which the folder type no longer declares.

Repair the settings on the instance. Read the item and its version with marfa items get <id>, then send the intended query, without search, with marfa folders change <id> --version <n> --file settings.json. Marfa never turns search into query, and editing .marfa/folder.yaml alone can't remove it. Change a folder's settings shows the file.

wrong_schema on a folder's storeCopy anchor link

A newer CLI can't open a store that another build of the core made. A folder command that writes, such as marfa folders push, pull, scan or watch, then counts the writes the store holds that the server hasn't taken, and acts on the count:

• None. If the store also holds no answer the folder has yet to record, the command replaces the store with one of its own shape, says so on standard error, and carries on. It changes no file and asks for no new first sync. The new store keeps the folder's record of its files, its first sync, its server and .marfa/folder.yaml, and fills again from the server. The command then sends the edits and deletions you made meanwhile, takes away the files of notes that went to the bin, and keeps holding a file the server refused before. An edit to a file whose note went to the bin meanwhile is sent as a new note.
• Some. The command leaves the store and the files as they are. Push the folder with the build that made the store, after marfa folders confirm if its first sync waits, then run the newer build again.
• Unknown. If the count can't be read, push the folder with the earlier build, remove it with marfa folders remove, which leaves its files, and add it again with the newer build.

The count includes each write the server gave up on, and each refused write the folder doesn't keep against a file, such as a deletion. A push doesn't send those again. If the count stays above zero after a push, remove the folder with the build that made the store and add it again with the newer build. If the server never took a deletion, the file comes back then: delete it again.

The command also leaves the store alone when it keeps its record of files in a shape the newer build can't carry: remove the folder with the earlier build and add it again. If the store names no folder, marfa folders add replaces it.

marfa folders status only reads, so it reports the refusal with the same advice and changes nothing.

A new file's default edge isn't appliedCopy anchor link

The folder's defaults.edges asked for an edge from a new item, and the working copy or the server refused it, such as when the collection is in the bin or the edge type doesn't admit the item's type. The file is sent and stays in step: only the edge is missing. The item and its file are kept, and a pull still writes the item's changes into the file.

The file carries the flag default_edge_refused, not refused, which marks an edit the server refused and a file held back. marfa folders status lists the file as in step with a reason that names the edge and the way out, and --json shows the flag:

notes/idea.md: in step, edge_constraint_violation (the folder's default in-collection edge to <id> was not applied; write that line in the file to apply it)

The push or scan that met the refusal says the file is sent and the folder's default edge not applied, and counts it apart from the files held or not sent.

• Refused by the working copy. The folder judges the edge again at each scan and makes it once the copy would take it, with no change to the file. Restore the collection, or fix the edge type, and sync.
• Refused by the server. The folder sends the edge once more after you next save the file, and not before.
• Clear it yourself. In a Markdown file, write the edge's line in the frontmatter, such as in-collection. For a file item, which has no lines, make the edge in an app, or take it out of the folder's defaults.

The refusal also clears when the edge is accepted, or when the item goes to the bin (default edge rules).

An attached file isn't writtenCopy anchor link

The server refused to show one file attached to a note, such as with 409 or 400. The pull writes every other file and leaves only that attachment out. The pull, and marfa folders status, report the note it is attached to with the flag attachment, naming the file's item and the reason:

notes/trip.md: its attached file <id> cannot be read (<reason>); it is written once it can be read

Each later pull asks for the file again, and writes it once the server shows it. Read the item with marfa items get <id> to see what the server answers, and fix that. A refused credential is different: it ends the pull, and the CLI shows how to sign in again. A file that can't be fetched for want of a network isn't reported, and comes with a later pull (attachment rules).

Links by name wait for the serverCopy anchor link

A folder finds the items its links and edge lines name, such as [[Reading list]], by asking the instance for many names in one request (Find items by title). When the instance refuses that request as a whole, marfa folders scan, push and watch say so once for the folder, not in each file's reason:

links by name wait, since the server has no title lookup (<error>); they are looked up again at each scan, so they resolve once the server is upgraded

The files are kept and their items made, and only the edges they name wait. An instance older than the CLI has no title lookup, so upgrade it. Any other refusal says the server refused a title lookup of several names with the instance's reason, which says what to fix. Nothing needs editing: the next scan asks again for every name that waited, and a watch repeats the line only when it changes (lookup rules).

Covered in their guidesCopy anchor link