aitbc/ai-memory/bug-patterns.md

Bug Patterns — AITBC Repository

This document records known bug patterns and their fixes to prevent reoccurrence.

---

Pattern: Service Import Name Shadowing in CLI

Symptom

KeyError: slice(None, 1, None)

or similar when invoking a CLI command that calls a service function.

Root Cause CLI command modules import a service function (e.g., generate_sar) and then define a Click command function with the same name. The command function overwrites the imported service reference, causing the command body to call itself or the Click object instead of the service.

Typical Code

from regulatory_reporting import generate_sar  # <-- import

@click.command()
def generate_sar(...):  # <-- name collision! Overwrites the import
    ...
    result = generate_sar(...)  # BAD: now refers to this function, not the service

Fix Rename the imported function using an alias (e.g., _svc suffix) and update all internal calls.

from regulatory_reporting import generate_sar as generate_sar_svc

@click.command()
def generate_sar(...):
    ...
    result = generate_sar_svc(...)  # GOOD: calls the actual service

Files Affected

• cli/aitbc_cli/commands/regulatory.py (primary example)

Prevention

• Use consistent import aliasing when names might clash.
• Consider naming CLI commands with a verb prefix (e.g., cmd_generate_sar) to avoid collision.
• Static analysis could flag functions that shadow imported names.

---

Pattern: Missing Service Dependencies in CLI Venv

Symptom

ModuleNotFoundError: No module named 'numpy'

or similar when running CLI commands that import service modules.

Root Cause CLI virtualenv lacks packages required by coordinator-api service modules (e.g., numpy, pandas, aiohttp, fastapi, uvicorn). The service modules are imported by CLI commands but their dependencies are not listed in the CLI's pyproject.toml.

Fix Add the missing dependencies to the CLI package dependencies and reinstall.

dependencies = [
    # existing...
    "numpy>=1.26.0",
    "pandas>=2.0.0",
    "aiohttp>=3.9.0",
    "fastapi>=0.111.0",
    "uvicorn[standard]>=0.30.0"
]

Then:

pip install -e ./cli

Files Affected

• pyproject.toml (root)
• CLI virtualenv (cli_venv/)

Prevention

• Keep service module dependencies in a shared location or explicitly list them in CLI deps.
• Run import tests in CI to catch missing deps early.

---

Pattern: Brother Chain Not Producing Blocks

Symptom Chain height stays at 0, transactions (e.g., mintFaucet) not confirmed.

Root Cause PoA proposer not defined as authority in the consensus configuration, or no node is acting as the authorized proposer.

Fix Ensure the genesis configuration includes the proposer as an authority and that the node's .env matches:

• PROPOSER_ID and PROPOSER_KEY set
• CHAIN_ID matches the genesis file
• Node started with proper PYTHONPATH

If still not producing, check logs for authority registration and consider creating a manual block or restarting with a proper genesis that includes the proposer.

Related Files

• apps/blockchain-node/src/aitbc_chain/consensus/poa.py
• .env for brother node
• Genesis YAML file

Prevention

• Provide a helper script to initialize a PoA chain with a single proposer for devnets.
• Document the proposer setup clearly.

---

End of bug patterns.