# M9 Build Blockers and Recovery

## Database connection failure

Symptoms:

- backend cannot connect to PostgreSQL,
- migrations fail,
- PostGIS extension missing.

Recovery:

1. Check Docker Compose service names.
2. Check environment variables.
3. Confirm database is reachable from backend container or local process.
4. Run a minimal connection test.
5. Do not replace PostGIS with SQLite except for explicitly isolated unit tests.

## PostGIS geometry error

Symptoms:

- invalid geometry,
- SRID missing,
- geometry column cannot be created.

Recovery:

1. Store all app geometry in EPSG:4326 unless a processing-specific CRS is required.
2. Validate GeoJSON before persistence.
3. Use Shapely for geometry validation.
4. Use PostGIS geometry column for persistent area/reference features.
5. Document any CRS transformation.

## Frontend API mismatch

Symptoms:

- UI expects raw data but API returns envelope,
- errors not shown,
- undefined data states.

Recovery:

1. Update frontend API client, not individual components.
2. Normalize envelope handling centrally.
3. Ensure every component handles loading, empty, error and ready states.

## Dependency installation failure

Symptoms:

- GDAL/Rasterio install errors,
- PyTorch package issue,
- platform binary mismatch.

Recovery:

1. Do not remove the feature from docs.
2. Add dependency note to `docs/DEPENDENCY_LOCK_PLAN.md`.
3. Implement interfaces and tests around pure-Python parts first.
4. Defer heavy binary package execution if needed, but leave adapter boundaries.

## External data unavailable

Symptoms:

- WFS unavailable,
- Sentinel catalog unavailable,
- credentials missing.

Recovery:

1. Use demo fixtures.
2. Keep adapter disabled but present.
3. Return explicit `external_service_unavailable` status.
4. Do not fake that live data was fetched.

## AI model unavailable

Symptoms:

- YOLO weights missing,
- SAM unavailable,
- GPU unavailable.

Recovery:

1. Build model registry and adapter interface.
2. Add CPU-safe mock inference only if marked as demo mode.
3. Keep output schema identical to real inference.
4. Do not present demo inference as production inference.

## Test failures

Recovery:

1. Fix tests if implementation is wrong.
2. Fix implementation if test reflects contract.
3. Update specs only if they are clearly inconsistent.
4. Document unresolved failures in execution log.