Research facilities 500 on a closed unit's factor (#2183)¶
Symptom¶
POST /v1/carbon-reports/15490/modules/research-facilities/research-facilities -> 500
{"detail":"Failed to create data entry"}
Backend log had the real reason, never returned to the client:
ValueError: data_entry_id=9237, emission_type='research_facilities__facilities',
factor_id=37756: The formula for 'research_facilities__facilities' could not
produce a value. Null inputs on the entry: none. Factor keys available:
['total_use', 'use_unit'].
Root cause chain¶
- Immediate cause:
ResearchFacilitiesCommonModuleHandler's formula (app/modules/research_facilities/handlers.py) needstotal_use,use_unit, andkg_co2eq_sumfrom the factor'svalues. Factor37756(researchfacility_id1012, CLIMACT-GE) only had{"total_use": 118750.0, "use_unit": "CHF"}—kg_co2eq_sumwas absent, not0. - Why it 500'd instead of silently zeroing (old behavior): #2050
Track J1 removed the silent-fallback that used to drop a leaf whose
formula returned
None, and madeprepare_createraise instead — by design, so an incomplete number doesn't ship as if it were complete. The route's genericexcept Exceptionthen flattened that into a bare 500, discarding the specific message. - Why
kg_co2eq_sumwas never populated: it's optional at factor creation, meant to be filled byResearchFacilitiesCommonFactorUpdateProvider.compute_factor_values(app/services/data_ingestion/computed_providers/research_facilities_common.py), which sums the unit'sCarbonReport.statsfor the year. CLIMACT-GE is a closed unit (Unit.is_active=False) — it has noCarbonReportfor the requested year and never will, so the provider's ownCarbonReport not foundguard raised on every recompute attempt instead of ever writing a value. The gap was permanent, not transient — a normal recompute could never fix it.
Fixes¶
CarbonReportModuleWorkflow.create/update— added a dedicatedexcept ValueErrorclause ahead of the genericexcept Exception, returning422withdetail=str(e)instead of a bare 500. Mirrors the existingIntegrityError-specific handling increate()and theValueErrorhandling already used indelete()._research_facilities_formula(common variant) — raises a specificValueErrornaming the facility whenkg_co2eq_sumis the missing key, instead of returningNoneand falling through to_apply_formula's generic message. Mirrors the animal variant's existing per-source raise.ResearchFacilitiesCommonFactorUpdateProvider.compute_factor_values— when theCarbonReportlookup misses and the unit is closed (is_active=False), returns{"kg_co2eq_sum": 0.0}instead of raising. A closed unit has stopped reporting; no report for the year is the expected case, and 0 is the correct total, not an unknown one. An active unit with no report for the year still raises — that case is a real data gap, not a closed-unit fact.
Combined: the client now gets a 422 naming the exact problem, and for the
closed-unit case specifically, the next factor recompute self-heals —
kg_co2eq_sum gets written as 0.0 and the entry create succeeds.
Not in scope here¶
- The one-off backfill of factor
37756itself (and any other already-affected closed-unit factors) — self-heals on the nextResearchFacilitiesCommonFactorUpdateProviderrecompute run for data_entry_type=research_facilities, year matching the affected factors; no manual data fix needed once this ships. - Whether other computed-factor providers have the same active-vs-closed-unit gap — not audited, worth a follow-up sweep if this pattern recurs elsewhere.
Verification¶
uv run pytest tests/unit— 2199 passed.- New regression tests:
test_create_value_error_from_emission_service_returns_422,test_update_value_error_from_emission_service_returns_422,tests/unit/modules/test_research_facilities_common_formula.py,test_closed_unit_with_no_carbon_report_returns_zero_sum. make lint,make type-check— clean.