Skip to content

Troubleshooting

Start from the same workspace configuration as the failed command. Keep its report, exit status and workflow identifier, and do not edit catalogue rows to repair state.

Check fails

Run Check from the project root:

weaver check

Check is local. Correct the first path, identity, metadata, SQL shape or dependency error it reports, then rerun it. Do not proceed to Build until Check succeeds.

A successful Check shows that Weaver can parse your project. It does not execute your authored code or prove Fabric access, permissions or remote Python imports.

Build fails

Read the Build report in action order, because completed actions may already have changed physical objects. Build does not roll them back when a later action fails.

  1. Run weaver check and correct source errors.
  2. Confirm that the selected configuration names the intended catalogue and targets.
  3. Correct the first failed declaration, permission or Fabric condition.
  4. Rerun the same Build selection.
  5. Run Health.
weaver build . --workspace-config workspace-development.yml
weaver health --workspace-config workspace-development.yml

The rerun reconciles the state Weaver finds; it does not resume the previous report. If Health reports an incomplete or incompatible catalogue, keep the evidence rather than writing catalogue tables manually or using Wipe as an ordinary Build repair.

Load fails

The Load report distinguishes failed, blocked and pending work. Correct the reported data, code, runtime or permission condition, then preview and rerun the intended item boundary:

weaver load \
  --dry-run \
  --workspace-config workspace-development.yml

weaver load \
  --workspace-config workspace-development.yml

A retry is a new Load against the state the previous run left. If you changed source during the correction, Build it first. Without fault tolerance, the first execution failure stops new scheduling; completed work remains applied. See Recover failed work for stale catch-up and deliberate Table reconstruction.

Test cannot run

A validation that could not run is different from a validation that ran and found bad data. For the former, correct the reported query, binding, permission or runtime condition.

If you changed the Test or Assumption source, Check and Build its owning item before rerunning Test:

weaver check
weaver build . --workspace-config workspace-development.yml
weaver test --workspace-config workspace-development.yml

Catalogue-mode Test executes installed validations. Source/file mode reads your authored files when you use --file or a catalogue-free workspace, and records no installed history. A validation that ran and failed is a data finding; investigate the diagnostic rows and the data-producing work, then rerun Test after correction.

Health is Amber

Amber usually means work is pending or stale rather than failed. Run Health, catch up non-Green Load work, run validations and check Health again:

weaver health --workspace-config workspace-development.yml
weaver load --stale --workspace-config workspace-development.yml
weaver test --workspace-config workspace-development.yml
weaver health --workspace-config workspace-development.yml

A rebuilt Table or Folder remains Pending until Load settles. A rebuilt validation remains Pending until Test runs. If a validation is stale because its inputs changed, Load the data first, then rerun Test.

Health is Red

Read the section and finding that caused Red:

  • Load: correct the failed or blocked work, then rerun the intended Load boundary.
  • Tests: correct the data or validation expectation, then rerun Test.
  • Build: reconcile the source and physical installation with Build; missing or contradictory catalogue state is not repaired by Load or Test.

Run Health again after the recovery operation. Red is not cleared by a successful unrelated command.

Runtime or authentication fails

To probe the named workspace independently of the project, run Doctor:

weaver doctor --workspace "Parcel Development"

Doctor reports the authentication and Fabric capabilities it could probe. It does not read your workspace configuration or show that a later command selects the intended catalogue, targets or Environment.

For authentication failures, confirm your credential path and workspace permission. Non-interactive execution does not fall back to browser sign-in.

For Python Load or Test work, confirm that your workspace configuration names an Environment, that the Environment exists, and that its latest definition was published successfully:

weaver fabric environment publish \
  --path Environment/ParcelRuntime.Environment \
  --workspace-config workspace-development.yml

Then rerun the failed Load or Test; publication does not resume it. Warehouse T-SQL work does not require a Fabric Environment, and desktop Lakehouse Build/Load/Test also needs a matching published Weaver runtime, including generated Spark SQL work. See Configure a workspace and Python runtime.

For exact command outcomes and catalogue evidence, use Operation behaviour and Reading the catalogue.

Windows output is garbled or cannot be decoded

Weaver configures its stdout and stderr streams as UTF-8, including when Windows gives the process a legacy console code page. If a Weaver command still reports an encoding failure, keep the command, terminal host and weaver --version; the CLI does not require a permanent system-wide UTF-8 setting.

A program that captures Weaver output must decode it as UTF-8. For example, use encoding="utf-8" with Python's subprocess.run rather than decoding the captured bytes with the Windows locale. If an older Python launcher or wrapper fails before Weaver configures its streams, set PYTHONUTF8=1 for that process as a compatibility workaround, then rerun the command. This workaround is not an installation prerequisite.