vitessio/vitess · error

don't know how to advance from %s to %s

Error message

don't know how to advance from %s to %s

What it means

vcopier's copy-task state machine maps each (state, nextState) pair to an advanceFn. If the machine reaches a state/next combination with no defined transition, it errors 'don't know how to advance', moves to vcopierCopyTaskFail, and jumps to END to fail the task. This indicates an unexpected state transition, i.e. an internal bug rather than user error.

Source

Thrown at go/vt/vttablet/tabletmanager/vreplication/vcopier.go:1194

					return nil
				}
				if err := vbc.insertCopyState(ctx, args.lastpk); err != nil {
					return vterrors.Wrapf(err, "error updating _vt.copy_state")
				}
				return nil
			}
		case vcopierCopyTaskCommit:
			advanceFn = func(context.Context, *vcopierCopyTaskArgs) error {
				// Commit.
				if err := vbc.Commit(); err != nil {
					return vterrors.Wrapf(err, "error committing transaction")
				}
				return nil
			}
		case vcopierCopyTaskComplete:
			advanceFn = func(context.Context, *vcopierCopyTaskArgs) error { return nil }
		default:
			err = fmt.Errorf("don't know how to advance from %s to %s", state, nextState)
			state = vcopierCopyTaskFail
			goto END
		}

		// tryAdvance tries to execute advanceFn, and also executes any
		// lifecycle hooks surrounding the provided state.
		//
		// If all lifecycle hooks and advanceFn are successfully executed,
		// tryAdvance will return state, which should be == the nextState that
		// we provided.
		//
		// If there was a failure executing lifecycle hooks or advanceFn,
		// tryAdvance will return a failure state (i.e. canceled or failed),
		// along with a diagnostic error.
		if state, err = task.lifecycle.tryAdvance(ctx, task.args, nextState, advanceFn); err != nil {
			goto END
		}
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Capture full vttablet logs including prior state names and report a bug with the workflow type and state sequence
2. Restart the workflow copy phase to reset task state
3. Upgrade/patch to a Vitess version where the state machine handles the missing transition
4. Avoid altering copy state rows in _vt.copy_state manually while tasks run

if err := task.run(ctx); err != nil {
  if strings.Contains(err.Error(), "don't know how to advance") {
    // internal state-machine bug: capture logs, fail the task,
    // restart the copy phase to reset state
  }
  return err
}

When it happens

Trigger: A copy task transitions to a nextState not covered by the switch on task state (e.g. an undefined intermediate state reached due to a logic bug or unexpected worker result).

Common situations: Vitess version bug in the copy-task state machine; corrupted worker results causing abnormal transitions; race between worker completion and task state updates.

Related errors

• unexpected: there are no tables to copy
• work queue is not open
• CopyAll was interrupted due to context expiration
• plan not found for table: %s, current plans are: %#v
• expecting field event first, got: %v

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/fbacd9f595b3b525. Report an issue: GitHub.