Error Codes

Stable error codes appear in error.code and command-specific findings.

Common examples:

• workbook_busy: another xlflow process holds the target workbook's coordination lock. The command fails immediately by default; JSON details include the workbook, attempted operation, and whether retrying is supported. Current owner metadata is included when available but is not authoritative.
• workbook_busy_timeout: an explicit --wait did not acquire every required workbook lock within the 30-second default or supplied --wait-timeout.
• workbook_busy_cancelled: Ctrl+C or caller cancellation stopped an explicit workbook wait before the command body started.
• workbook_recovery_required: the normal OS lock was acquired, but a previous operation left the workbook in an uncertain Excel/VBA state. The command body does not start, the failure is not retryable, and --wait will not recover it. Follow error.details.recovery_actions.
• workbook_recovery_verification_failed: normal recovery clear could not prove that the recorded Excel PID no longer exists, or the marker did not contain verifiable process information. The marker remains.
• workbook_recovery_publication_failed: xlflow detected an uncertain termination but could not atomically publish its recovery marker. Stop or close Excel manually before attempting more workbook work.
• coordination_recovery_check_failed: xlflow could not safely read recovery state after acquiring the workbook lock. Unsafe operations fail closed.
• coordination_wait_args_invalid: --wait-timeout was used without --wait, or the timeout was not positive.
• coordination_wait_unsupported: the selected command is not a retryable, non-parallel-safe workbook operation.
• coordination_status_unavailable (warning): session status could not probe workbook coordination state. Existing session status fields and exit behavior remain available, while the top-level coordination field is omitted.
• vbide_access_denied
• macro_failed
• macro_not_found
• runner_not_invocable
• macro_timeout
• vba_compile_failed
• gui_boundary_detected
• source_preflight_failed
• output_file_exists
• unsupported_image_format
• form_not_found
• FRM202
• spec_validation_failed
• fmt_failed
• fmt_check_failed
• fmt_skipped_unsupported_extension
• fmt_args_invalid
• fmt_stdin_read_failed
• fmt_stdin_write_failed
• source_encoding_invalid
• pack_source_encoding_failed
• pack_validation_failed
• encoding_args_invalid
• encoding_check_failed
• encoding_convert_failed
• encoding_convert_rollback_failed
• windows_xlflow_not_found
• wsl_project_path_unsupported
• wsl_path_translation_failed
• windows_xlflow_execution_failed

Lint codes include VB001 through VB015, VB018 through VB023, and VB026 through VB066. VB066 is a non-blocking style warning for VBE-accepted Property Get terminators; the other compile-dialog prevention range remains VB065 and below. Analyzer codes include VBA101 through VBA106, runtime-risk findings VBA201 through VBA259, Excel semantic inspections VBA260 through VBA262, unused-declaration findings VBA265 through VBA269, the worksheet cell-reference collision finding VBA270, and Option Base inconsistency findings VBA271 and VBA272; VBA248 is a maintainability finding, VBA250 is an active-state runtime-safety finding, VBA251 is a reliability warning for implicit approximate lookup mode, VBA252 is a correctness warning for unavailable typed WorksheetFunction members, VBA253 through VBA255 cover implicit, unbound, and bang default-member access, VBA256 covers dead scalar stores, VBA257 and VBA258 cover discarded Function return values, VBA259 covers unreachable Select Case branches, VBA260 through VBA262 cover worksheet-name access, worksheet-function dispatch, and host bracket expressions, VBA265 through VBA269 cover unused parameters, private constants, user-defined type members, and unassigned or prematurely read variables, VBA270 covers worksheet-visible functions named after valid cell references, and VBA271 and VBA272 cover zero-based ParamArray parameters and qualified VBA.Array calls under Option Base 1.

VBA249 may use the runtime-error kinds default_member_required and default_member_cycle when complete type and default-member facts prove a deterministic failure. These findings are non-blocking. VBA202 remains the owner of proven error-91 object-use-before- Set/Nothing failures.

Recovery map

Code or symptom	Likely cause	Recovery
vbide_access_denied	Excel Trust Center blocks VBIDE automation.	Enable Trust access, restart Excel, rerun doctor.
macro_not_found	The target name is not a runnable qualified procedure.	Run macros --json and use qualified_name.
source_preflight_failed	Source would trigger a VBE compile/dialog failure.	Fix the reported source issue, then rerun lint and push.
source_encoding_invalid	A managed .bas, .cls, or .frm is not UTF-8 without BOM.	Run xlflow encoding check; save UTF-8/UTF-16 BOM files as UTF-8 without BOM, or run xlflow encoding convert --from cp932 only for non-BOM CP932 input.
pack_source_encoding_failed	Valid UTF-8 source contains a character unavailable in the target VBA project code page.	Use a representable character or configure/import a workbook with the intended project code page; source is left unchanged.
pack_validation_failed	pack found multiple source or compiler validation issues.	Review each issue's code and source location, correct the reported inputs, and rerun pack --check.
vba_compile_failed / 0x800A03EC	Excel rejected imported VBA or a workbook operation.	Use run --diagnostic, inspect the source location, and retry only after preflight passes.
macro_timeout	A macro loop or modal UI did not complete.	Inspect dialogs and session state; use interactive mode only with a human.
workbook_recovery_required	Excel/VBA termination was not proven safe.	Follow recovery; --wait cannot clear quarantine.
windows_xlflow_not_found	WSL cannot locate the Windows frontend.	Install it or set XLFLOW_WINDOWS_EXE; see WSL troubleshooting.
wsl_project_path_unsupported / wsl_path_translation_failed	The project is outside a Windows-mounted path.	Move it under /mnt/c, /mnt/d, or another mounted drive.

The symptom-oriented troubleshooting guide adds diagnosis and verification steps for each category.