Skip to content

Recover an Interrupted Command

A command that rewrites your working files can be interrupted before it finishes, by pressing Ctrl-C, by closing the terminal, or by the machine losing power. It also stops before it finishes when it cannot change some of your files, such as a file another program has open, or one whose content could not be downloaded. Either way, the workspace may be left part-way between two revisions, in an inconsistent state.

This affects fxv sync, fxv goto, fxv revert, fxv resolve, fxv branch switch and fxv copy. Nothing is lost when one of them is interrupted or stops, but the workspace has to be returned to a consistent state before you can carry on working.

Recognize the state

Most commands refuse to run and tell you what happened:

$ fxv status
Error: A previous `fxv goto` was interrupted and this workspace is in an inconsistent state.

Was going from main.2 to main.30.
208,983 of 254,082 planned file change(s) applied, 45,099 remaining.

Run fxv resume to finish the command, or fxv resume --rollback to roll it back.

The report identifies the command that was interrupted, the revisions it was moving between, and how far it got. Scripts can detect this without parsing the message: the command exits with status code 98, and under --format json the same detail is available in the error payload.

If the command stopped because files could not be changed

When a command cannot write or delete some files, it still changes every other file in its plan, then stops and lists the files it could not change, grouped by the reason and what to do about it:

$ fxv sync
Error: 2 file change(s) could not be applied, so this command stopped and the workspace is in an inconsistent state.

Was syncing from main.41 to main.42.
1,206 of 1,208 planned file change(s) applied, 0 remaining (2 failed).

Another program has these files open. Close the program:
  Content\Maps\Main.umap (Access denied for D:\work\game\Content\Maps\Main.umap)

Permission to change these files was denied. Check the permissions of the files and their directories, or whether another program is using them:
  Binaries\Win64\Game.dll (Access denied for D:\work\game\Binaries\Win64\Game.dll)

Run fxv resume to finish the command, or fxv resume --rollback to roll it back.

The usual causes are:

  • Another program has the file open, such as an editor with the asset loaded. Close the program, or the file in it.
  • The file is a program or library that is running, or you do not have permission to change it. Stop the program, or check the file's permissions.
  • The file's content could not be downloaded because the network connection dropped. Check the connection.

Fix the cause, then run fxv resume. It tries the files that failed again, along with anything else left to do. If a file still cannot be changed, the command stops again with the same report.

Until you recover the workspace, other commands report the stopped command and list the files under the same reasons, without each file's error message.

If the command stopped before changing any files

FlexVault always preserves your local changes, and does not run an action that could overwrite a file it has not preserved. These commands snapshot your workspace before they change it, so when a changed file cannot be read, the command stops to avoid losing your changes:

$ fxv sync
Error: 1 path(s) could not be read, so the working directory was not updated
  Content\Maps\Main.umap: IO error: The process cannot access the file because it is being used by another process. (os error 32)

Close anything using them or fix their permissions, then run the command again.

The workspace is not left in an inconsistent state, so there is nothing to resume. Close the program using the file or fix its permissions, then run the same command again.

If the command stops with Too many files are open, it also changed no files. See Raise the open file limit.

Choose a direction

There are two options for recovering an interrupted command.

Continue finishes the interrupted command and arrives at the revision it was moving to. Choose this when you still want the result you originally asked for.

fxv resume

Continuing is the default, so fxv resume and fxv resume --continue do the same thing.

Roll back undoes the interrupted command and returns the workspace to the revision it was on before it started. Choose this when you would rather be back where you were.

fxv resume --rollback

Rolling back is not available when the interrupted command was itself a rollback (see below), or when the workspace had never finished a sync before it, since there is no earlier revision to return to. The report then offers only fxv resume.

Any local changes made between the interruption and the recovery are moved aside and committed as a draft revision rather than overwritten, so no work is discarded - like other commands in FlexVault, fxv resume is safe and will never discard changes.

If the recovery is itself interrupted

Interrupting a recovery is safe. It leaves the workspace in the same inconsistent state, and fxv resume picks up from wherever it stopped. You can interrupt and resume as many times as you need.

One thing to know about rolling back: it is not the exact inverse of the interrupted command, it is a new command planned in the opposite direction. Once a rollback has started, the original command can no longer be continued, and fxv resume will continue the rollback instead.

After a power loss

A power loss can leave files on disk in a state that a stopped process cannot, so a plain recovery may accept a file that was only partly written. In this case, prefer to use the --full option - this is typically not needed, and should be used only when the machine lost power or crashed.

fxv resume --full

--full re-checks and re-syncs every file in the interrupted command's plan, including those already recorded as finished. It reads far more data and takes considerably longer, so it is worth using only when you are concerned about the integrity of the workspace due to a power loss or crash.

If fxv resume cannot read the interruption

To continue or roll back, FlexVault needs the record the interrupted command left behind, which says how far it got. If that record is damaged, neither direction is available and fxv resume reports that it cannot act:

$ fxv resume
Error: A previous sync was interrupted and its journal cannot be read, so this workspace is in an inconsistent state.

D:\work\game\.fxv_workspace\state\sync_progress.rkyv (Internal error: Sync journal magic bytes do not match)

Neither fxv resume nor fxv resume --rollback can act on it. Run fxv doctor reset-sync to discard the journal and move the workspace to a known revision.

Recover by moving the workspace to a revision you choose, instead of trying to finish the interrupted command:

fxv doctor reset-sync

Without --revision, the reset moves the workspace to the latest published revision on the current branch, the same target fxv sync uses. Specify a different one with --revision main.456. The command shows what it is about to do and asks for confirmation first.

Resetting gives up the ability to continue or roll back the interrupted command, and that is all it gives up. Your files are snapshotted as a draft revision before anything is moved, so whatever the workspace held at the time of the reset stays recoverable through fxv history and fxv goto.

Use this only when fxv resume tells you it cannot read the interrupted command. While fxv resume still runs, prefer it, because it knows what the interrupted command was doing and the reset does not.