BranchPy
Log in

Docs-Builder

# Analysis Troubleshooting

Version: 1.1.1
Last Updated: January 23, 2026

Common Issues

  • Invalid semantics YAML: /semantics/update returns 422 or CLI warns; fix placeholders/effect types, retry update (backups in .branchpy/semantics/.backup/).
  • Unresolved dynamic jumps: dynamic_jump_unresolved warnings in flow; add semantics entries or ensure dataflow variables are resolvable; unresolved jumps stay warnings.
  • Unreachable labels/statements: Reported by CFG/propagation; check missing entry labels or terminal nodes cutting SEQ edges.
  • PFI finds zero functions: Verify .rpy files exist and project root path is correct; confirm Python blocks are parseable.
  • PFI missing stat modifiers: Run full analysis; pass known stats via --stats; ensure SAE/semantics catalog is current.
  • PFI governance log absent: Ensure home folder write perms; disable governance explicitly if undesired (enable_governance=False).
  • AI provider errors: Invalid API keys or unsafe configs; run provider validate_config, set safe_mode=True to restrict to local providers.

Verification Steps

  • branchpy semantics2 flow --project <path> --json to confirm flow metrics and warnings.
  • branchpy analyze --debug-cfg cfg.dot then render DOT to inspect edges.
  • branchpy pfi -p <path> --show-warnings --show-dead to validate PFI coverage.
  • Inspect semantic trace export for expected actions and no UNKNOWN placeholders.

Artifacts & Logs

  • Semantics backups: .branchpy/semantics/.backup/semantics-*.yaml.
  • CFG DOT (debug): cfg.dot (user-specified path).
  • PFI exports: .branchpy/cache/function_index.json (default) or user-specified.
  • Governance log (optional): ~/.branchpy/pfi_governance.jsonl.