Skip to main content
Virtual mode has explicit recovery paths for common failure scenarios. SQLBuild blocks cleanly rather than leaving ambiguous state, and error messages point to the specific recovery action needed.

​
State corruption

ScenarioErrorRecovery
Missing state table”Cannot backup invalid state schema” on state migratesqb state reset --auto-approve then sqb state init
Missing state columnSameSame
Wrong state column typeSameSame
Deleted backup schema (explicit id)Rollback blocks with backup-id errorUse a different backup or reset
All backups deleted”No state backup is available for rollback”sqb state reset --auto-approve then reinitialize
State corruption is detected by schema validation during state migrate. If the current state schema is invalid, SQLBuild refuses to back it up (to avoid persisting a broken snapshot) and directs you to reset.

​
Warehouse drift

ScenarioDetectionRecovery
Missing logical VDE viewsqb reconcile reports missing viewsqb reconcile repair-view for the affected model
Missing physical relationsqb reconcile reports it, repair-view blocksRebuild with sqb build --select
Logical target is a table, not a viewrepair-view and attach blockDrop the table manually, then repair-view
Checkpoint physical relation missingsqb rollback blocksUse a more recent checkpoint, or rebuild
Promoted physical relation missingsqb promote blocksRebuild the source VDE first

​
Lock conflicts

ScenarioErrorRecovery
VDE locked by another process”virtual environment is locked”Wait for the other process, or clear the lock
Lock held by crashed processSamesqb state locks clear with --force
Only clear locks when you are certain the holding operation is no longer running.

​
Interrupted operations

ScenarioBehaviorRecovery
Interrupted adoptFailed operation recorded. Physical schema may have partial artifacts.sqb reconcile to diagnose, manual repair if needed, retry.
Interrupted detachFailed operation recorded. VDE stays finalized. Physical version preserved.sqb reconcile to diagnose, retry detach.
Interrupted promotionFailed operation recorded. Target VDE lock released.Retry promote.
There is no automatic resume command for interrupted operations. SQLBuild records the failure in state_operations and state_operation_events, preserves VDE refs and checkpoints, and leaves recovery to the operator. To inspect a failed operation: 
SELECT operation_id, operation_type, status, virtual_environment_name
FROM sqlbuild_state.state_operations
WHERE status = 'failed';

SELECT operation_id, action, status, message
FROM sqlbuild_state.state_operation_events
WHERE operation_id = '<id>'
ORDER BY created_at;

​
Mode guards

SQLBuild blocks operations that don’t apply to the current mode:
OperationDirect modeVirtual mode
sqb state subcommandsBlockedAllowed
sqb build --no-tests --no-auditsAllowedBlocked (use sqb build)
sqb build --defer-toAllowedBlocked (VDE refs handle upstream resolution)
sqb promoteBlockedAllowed
sqb rollbackBlockedAllowed
sqb reconcileBlockedAllowed

​
Detached VDE guards

After sqb state detach, the VDE is marked detached and blocked from further virtual operations:
OperationBehavior
sqb buildBlocks: “virtual environment is detached”
sqb promote --from <detached>Blocks
sqb promote --to <detached>Blocks
sqb rollbackBlocks
The project can continue in standard mode or re-adopt to return to virtual mode.

​
Adopt guards

ConditionError
No unsuffixed_virtual_env configuredBlocks with config guidance
Copy fallback needed without --allow-copy”requires —allow-copy”
Wrong typed confirmationCancelled, no changes made

​
Detach guards

ConditionError
VDE not finalized”requires a finalized virtual environment”
Copy fallback needed without --allow-copy”requires —allow-copy”
Wrong typed confirmationCancelled, no changes made

​
General recovery strategy

  1. Diagnose with sqb reconcile or by querying state tables directly
  2. Repair views with sqb reconcile repair-view for missing/broken logical views
  3. Rebuild with sqb build --select <model> for missing physical versions
  4. Roll back with sqb rollback to restore a prior finalized state
  5. Reset state with sqb state reset --auto-approve as a last resort (drops all virtual state)
When in doubt, sqb reconcile is the starting point. It reports what’s wrong without changing anything.