134 lines
4.9 KiB
Markdown
134 lines
4.9 KiB
Markdown
# Failure Archive
|
||
|
||
This archive collects known failure patterns experienced during development, along with their causes and resolutions. Agents should consult before debugging similar symptoms.
|
||
|
||
---
|
||
|
||
## Failure: CLI Fails to Launch – Hardcoded Absolute Paths
|
||
|
||
**Date**: 2026-03-13
|
||
|
||
**Symptom**: `ImportError: No module named 'trading_surveillance'` when running `aitbc --help` or any subcommand.
|
||
|
||
**Cause**: Multiple command modules in `cli/aitbc_cli/commands/` used:
|
||
```python
|
||
sys.path.append('/home/oib/windsurf/aitbc/apps/coordinator-api/src/app/services')
|
||
```
|
||
This path is user-specific and does not exist on the `aitbc1` host.
|
||
|
||
**Modules affected**:
|
||
- `surveillance.py`
|
||
- `ai_trading.py`
|
||
- `ai_surveillance.py`
|
||
- `advanced_analytics.py`
|
||
- `regulatory.py`
|
||
- `enterprise_integration.py`
|
||
|
||
**Resolution**:
|
||
1. Added `__init__.py` to `apps/coordinator-api/src/app/services/` to make it a proper package.
|
||
2. Updated each affected command module to use:
|
||
```python
|
||
sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', '..', 'apps', 'coordinator-api', 'src'))
|
||
from app.services.trading_surveillance import ...
|
||
```
|
||
(or simply `from app.services import <module>` after path setup)
|
||
3. Removed hardcoded fallback absolute paths.
|
||
4. Verified: `aitbc --help` loads without errors; `aitbc surveillance start` works.
|
||
|
||
**Prevention**: Use package-relative imports; avoid user-specific absolute paths. Consider making coordinator-api a proper installable dependency.
|
||
|
||
---
|
||
|
||
## Failure: Missing Dependency – aiohttp
|
||
|
||
**Symptom**: `ModuleNotFoundError: No module named 'aiohttp'` when importing `kyc_aml_providers.py`.
|
||
|
||
**Cause**: `cli/pyproject.toml` did not declare `aiohttp`.
|
||
|
||
**Resolution**: `poetry add aiohttp` (or `pip install aiohttp` in venv). Updated `pyproject.toml` accordingly.
|
||
|
||
**Prevention**: Keep dependencies declared; run tests in fresh environment.
|
||
|
||
---
|
||
|
||
## Failure: Package Build Fails Due to Missing README.md
|
||
|
||
**Symptom**: `poetry build` for `packages/py/aitbc-agent-sdk` fails with `FileNotFoundError: README.md`.
|
||
|
||
**Cause**: The package directory lacked a README.md, which some build configurations require.
|
||
|
||
**Resolution**: Created an empty or placeholder README.md. Later enhanced with usage examples.
|
||
|
||
**Prevention**: Ensure each package has at least a minimal README; add pre-commit hook to check.
|
||
|
||
---
|
||
|
||
## Failure: Starlette Broadcast Module Missing After Upgrade
|
||
|
||
**Symptom**: `ImportError: cannot import name 'Broadcast' from 'starlette'` after upgrading Starlette to 0.38+.
|
||
|
||
**Cause**: Starlette removed the Broadcast module in version 0.38.
|
||
|
||
**Impact**: P2P gossip backend (using Redis broadcast) fails to import. Services crash on startup.
|
||
|
||
**Resolution**:
|
||
- Pinned Starlette to `>=0.37.2,<0.38` in `pyproject.toml`.
|
||
- Added comment explaining the pin and that production should replace broadcast with direct P2P.
|
||
|
||
**Prevention**: Avoid upgrading Starlette without testing; track deprecations.
|
||
|
||
**See also**: `debugging-notes.md` for diagnostic steps.
|
||
|
||
---
|
||
|
||
## Failure: Docker Compose Not Found
|
||
|
||
**Symptom**: `docker-compose: command not found` even though Docker is installed.
|
||
|
||
**Cause**: System has Docker Compose v2 (`docker compose`) but not v1 (`docker-compose`). The project documentation referenced `docker-compose`.
|
||
|
||
**Resolution**: Updated documentation to use `docker compose` (or detect whichever is available). Alternatively, create a symlink or alias.
|
||
|
||
**Prevention**: Detect both variants in scripts; document both names.
|
||
|
||
---
|
||
|
||
## Failure: Test Scripts Use Absolute Paths
|
||
|
||
**Symptom**: `run_all_tests.sh` fails with "No such file or directory" for test scenario scripts located in `/home/oib/windsurf/aitbc/...`.
|
||
|
||
**Cause**: Test scripts referenced a specific user's home directory, not the project root.
|
||
|
||
**Resolution**: Rewrote paths to be project-relative using `$(dirname "$0")`. Example: `$(dirname "$0")/test_scenario_a.sh`.
|
||
|
||
**Prevention**: Never hardcode absolute paths; always compute relative to project root or script location.
|
||
|
||
---
|
||
|
||
## Failure: Gitea API Unstable During PR Approval
|
||
|
||
**Symptom**: Script `monitor-prs.py` fails to post approvals due to "connection reset" or 5xx errors from Gitea.
|
||
|
||
**Cause**: Gitea instance may be under load or temporarily unavailable.
|
||
|
||
**Resolution**: Added retry logic with exponential backoff. If still failing, log and skip; next run will succeed.
|
||
|
||
**Prevention**: Make API clients resilient to transient failures.
|
||
|
||
---
|
||
|
||
## Failure: Coordinator API Idempotent DB Init
|
||
|
||
**Symptom**: Running `init_db()` multiple times causes `sqlite3.IntegrityError` due to duplicate index creation.
|
||
|
||
**Cause**: `init_db()` did not catch duplicate index errors; it assumed fresh DB.
|
||
|
||
**Resolution**: Wrapped index creation in try/except blocks catching `sqlite3.IntegrityError` (or using `IF NOT EXISTS` where supported). This made initialization idempotent.
|
||
|
||
**Impact**: Coordinator can be started repeatedly without manual DB cleanup.
|
||
|
||
**Prevention**: Design DB initialization to be idempotent from the start.
|
||
|
||
---
|
||
|
||
*Add new failures chronologically below.* |