# Known Issues

**Last updated: 2026-08-05**

Issues and limitations identified after publication, across all releases in this repository.

Statuses are dated. If your copy of this file is older than the dates below, re-fetch it — an issue recorded as open here may since have been resolved, and vice versa.

This file supersedes `2022/KNOWN_ISSUES.md`, which covered only the 2022 releases and was not reachable from anywhere else in the repository. That file remains in place so existing links keep working.

Each issue is also recorded in [`catalog.json`](catalog.json) under `known_issues`, and referenced from the affected releases' entries via `known_issue_ids`, so automated consumers can check for issues without parsing this document.

<!-- BEGIN ID-MAP (generated) -->
| Issue | `catalog.json` id | Issue | `catalog.json` id |
|---|---|---|---|
| KI-001 | `split-aggregates-2025-resstock` | KI-017 | `resstock-2025-enumeration-dictionary-not-utf8` |
| KI-002 | `upgrade-lookup-incomplete-amy2012-2025` | KI-018 | `resstock-2025-readme-amy2012-defined-as-2018` |
| KI-003 | `missing-dictionaries` | KI-019 | `resstock-2025r1-electric-panel-capacity` |
| KI-004 | `dictionary-schema-variants` | KI-020 | `resstock-2025r1-column-applicability` |
| KI-005 | `upgrade-id-rendering-inconsistent` | KI-021 | `resstock-2024r2-electricity-energy-bills` |
| KI-006 | `comstock-2025r3-california-swh` | KI-022 | `resstock-2024r2-measure-applicability` |
| KI-007 | `comstock-2025r2-package-naming` | KI-023 | `resstock-wall-type-maine` |
| KI-008 | `dead-documentation-links` | KI-024 | `comstock-california-warehouse-hvac` |
| KI-009 | `readme-directory-mismatch` | KI-025 | `comstock-california-equipment-power-density` |
| KI-010 | `unresolvable-upgrade-numbering-2024-1` | KI-026 | `comstock-california-ventilation-rates` |
| KI-011 | `amy2012-missing-directories` | KI-027 | `comstock-2024r2-utility-bills-emissions` |
| KI-012 | `small-sample-county-aggregates` | KI-028 | `comstock-2024r2-aggregate-discrepancy` |
| KI-013 | `comstock-field-name-missing-unit-suffix` | KI-029 | `comstock-2025r2-hawaii-amy2012-weather` |
| KI-014 | `comstock-dictionary-stale-2025r2` | KI-030 | `comstock-2025r3-package-naming` |
| KI-015 | `comstock-undocumented-weight-applicability` | KI-031 | `empty-occupancy-schedule-files-2021` |
| KI-016 | `resstock-2025-columns-omitted-from-amy2018` | KI-100 | `kiva-foundation-2022` |

**13 of these affect published results**: KI-006, KI-007, KI-019, KI-021, KI-022, KI-023, KI-024, KI-025, KI-026, KI-027, KI-028, KI-029, KI-100.
<!-- END ID-MAP -->

## Status

Each entry states where it stands as of the **Last updated** date above, rather than describing the repository as it once was. Several issues were resolved by the same change that published this file, so they are dated to it.

The same values are in `catalog.json` as `known_issues[].status` and `known_issues[].status_date`, so an automated consumer can filter without parsing this document.

<!-- BEGIN STATUS (generated) -->
| Issue | Status | Issue | Status |
|---|---|---|---|
| KI-001 | Fix in progress | KI-017 | **Resolved 2026-08-05** |
| KI-002 | Open | KI-018 | **Resolved 2026-08-05** |
| KI-003 | Partially resolved | KI-019 | Open |
| KI-004 | Partially resolved | KI-020 | Open |
| KI-005 | Will not be changed | KI-021 | Open |
| KI-006 | Open | KI-022 | Open |
| KI-007 | Open | KI-023 | Open |
| KI-008 | **Resolved 2026-08-05** | KI-024 | Open |
| KI-009 | Partially resolved | KI-025 | Open |
| KI-010 | Open | KI-026 | Will not be changed |
| KI-011 | Open | KI-027 | Open |
| KI-012 | Inherent | KI-028 | Open |
| KI-013 | **Resolved 2026-08-05** | KI-029 | Will not be changed |
| KI-014 | Open | KI-030 | Will not be changed |
| KI-015 | Open | KI-031 | Will not be changed |
| KI-016 | Will not be changed | KI-100 | Will not be changed |
<!-- END STATUS -->

| Status | Meaning |
|---|---|
| **Open** | Still true as of the date above |
| **Fix in progress** | Scheduled work that has not yet landed |
| **Resolved `<date>`** | The fix has landed as of that date. Recorded rather than deleted, so anyone holding an earlier copy of the data or documentation knows what changed |
| **Partially resolved** | Corrected in the new file; the original artifact still carries the defect |
| **Will not be changed** | Permanent, by decision. The workaround is the answer |
| **Inherent** | A property of the data, not a defect to repair |

**Severity**

| Level | Meaning |
|---|---|
| **Critical** | Will silently produce wrong or missing results for a common access pattern |
| **Significant** | Affects correctness of results or blocks a documented use |
| **Caution** | Requires a workaround; failure is visible |
| **Informational** | Worth knowing; no action required |

---

## Open issues

### KI-001 · Aggregates for upgrades 29–32 published to the wrong location
**Severity:** Critical · **Identified:** 2026-08-04 · **Affects results:** No — affects data retrieval
**Status: fix in progress — data is being regenerated in the correct location**

**Affected:** `2025/resstock_amy2018_release_1`, `2025/resstock_amy2012_release_1`

`upgrades_lookup.json` defines upgrade IDs 0–32, but `timeseries_aggregates/` contains only upgrades **0–28**, across all four geographic partitionings. Aggregates for upgrades 29–32 were written to a temporary location, `timeseries_aggregates_new_env/`, which holds `upgrade=0, 29, 30, 31, 32`.

Requesting an aggregate for upgrades 29–32 from `timeseries_aggregates/` yields a key that does not exist — **no data, no error**.

**Resolution.** These aggregates are being regenerated under `timeseries_aggregates/upgrade={id}/` in the standard convention. Once that completes, `timeseries_aggregates/` will cover the full upgrade range and `timeseries_aggregates_new_env/` will be removed.

**Interim access.** Until the regenerated data is published, upgrades 29–32 are reachable only at:

```
timeseries_aggregates_new_env/by_{geography}/upgrade={id}/{geography}={value}/
```

This path is temporary. **Do not build against it** — it will be deleted. Note also that leaves there mix unchunked CSV with Parquet split as `<base>_chunk_<i>_of_<n>.parquet`; a leaf may hold 37 files where the correct tree holds 5, and reading a single chunk returns a fraction of the data with no indication it is partial. The regenerated data will follow the standard unchunked CSV convention.

---

### KI-002 · `upgrades_lookup.json` is incomplete
**Severity:** Significant · **Identified:** 2026-08-04 · **Affects results:** No
**Status: open — the lookup file has not been corrected**

**Affected:** `2025/resstock_amy2012_release_1`

The lookup defines upgrade IDs 0–28, but published aggregates for upgrades 29, 30, 31, and 32 exist in that release. The lookup was not updated when those upgrades were added. Its sibling `2025/resstock_amy2018_release_1` defines all 33.

Consequently, an agent enumerating upgrades from the lookup silently omits four, while one resolving an ID from a partition name finds no definition for it.

**Workaround.** Names for upgrades 29–32 can be taken from `2025/resstock_amy2018_release_1/upgrades_lookup.json`, which covers the same measures. This should be corrected in place when KI-001 is resolved.

---

### KI-003 · Two releases carry a provisional dictionary copied from a sibling
**Severity:** Significant · **Identified:** 2026-08-04 · **Affects results:** No
**Status: partially resolved — both releases now have dictionaries, but neither is verified against its own data**

**Affected:** `2025/comstock_amy2018_release_1`, `2025/resstock_amy2012_release_1`

Neither release published a `data_dictionary.tsv` or `enumeration_dictionary.tsv` of its own. Each now carries a copy taken from its nearest sibling, so column names, types, units and permitted values are available — but the copy describes a **different release**, and the completeness pass measured how far off each one is.

| Release | Copied from | Columns in the data with no entry | Documented fields not in the data |
|---|---|---:|---:|
| `2025/comstock_amy2018_release_1` | `2025/comstock_amy2018_release_2` | 346 | 405 |
| `2025/resstock_amy2012_release_1` | `2025/resstock_amy2018_release_1` | 104 | 3 |

Both copies carry `status=provisional` in their provenance line and `standardized_schema: false` in `catalog.json`. **Treat descriptions and enumerations as indicative, not authoritative.**

The two copies are imperfect for different reasons, and each has its own entry:

- **The ComStock copy inherits a stale source.** `release_2`'s own dictionary lags its data by roughly the same margin — see KI-014. Correcting Release 2 corrects this copy too.
- **The ResStock copy is missing the sibling's extra outputs.** 82 of its 104 undocumented columns are the component-load columns that exist only in this release — see KI-016. The remaining 22 are gaps the AMY 2018 dictionary already had.

A dictionary that silently describes a different release is worse than no dictionary, because the consumer cannot tell it is wrong. That is why the provisional marking exists and why it should stay until each copy is verified.

---

### KI-004 · Data dictionary column layout differs between releases
**Severity:** Caution · **Identified:** 2026-08-04 · **Affects results:** No
**Status: partially resolved — a standardized file now exists for every release; the pre-2025 originals are unchanged beside it**

**Affected:** All releases

Seven header layouts exist for `data_dictionary.tsv` and six for `enumeration_dictionary.tsv`. Two differences matter:

- **Column order flips by dataset type.** ComStock writes `field_name, field_location, …`; ResStock writes `field_location, field_name, …`. Parsing by position mislabels every row in one of the two.
- **The enumerations column is inconsistent.** It appears as `allowable_enumeration`, `allowable_enumerations`, `allowable_enumerations_baseline`, and `allowable_baseline_enumerations` — and is **absent entirely** in `2025/resstock_amy2018_release_1`.

`2021/resstock_amy2018_release_1` and `2021/resstock_tmy3_release_1` additionally have an unnamed first column in `enumeration_dictionary.tsv`.

**Workaround.** Parse by header name, never by position. Where the enumerations column is missing, derive it from `enumeration_dictionary.tsv`, which is scoped by `metadata_column`. `catalog.json` records the schema variant for every release.

---

### KI-005 · Upgrade ID rendering is inconsistent
**Severity:** Caution · **Identified:** 2026-08-04 · **Affects results:** No
**Status: will not be changed — settled as a forward convention only; published keys are not renamed**

**Affected:** All releases with upgrades

The same upgrade ID is rendered differently depending on directory and dataset:

| | ResStock | ComStock |
|---|---|---|
| Partition directory, timeseries | `upgrade=0` | `upgrade=0` |
| Partition directory, models | `upgrade=0` | `upgrade=00` |
| Aggregate filename | `up00-` | `up0-` |
| Individual timeseries filename | `-0.parquet` | `-0.parquet` |
| Annual results filename | `_upgrade0` | `_upgrade0` |

The aggregate filename prefixes **agree for two-digit IDs and disagree for single-digit ones**. Code written for ResStock and tested on upgrade 10 works, then returns nothing for upgrades 0–9 against ComStock — including the baseline, the most frequently requested scenario. This tends to surface in production rather than in testing.

`bldg_id` is similarly rendered zero-padded to 7 digits in model filenames and unpadded elsewhere.

**Workaround.** Use the `key_template` and `filename_rendering` fields in each release's `manifest.json` rather than reusing a pattern across directories.

---

### KI-006 · Service water heating not modeled in California — ComStock 2025 Release 3
**Severity:** Significant · **Affects results:** **Yes**
**Status: open — no corrected release for California**

**Affected:** `2025/comstock_amy2018_release_3`

Because of a workflow error, **service water heating was not modeled in any California buildings** in this release. Energy consumption and EUI are understated for affected buildings, with the largest impact on building types with high hot-water demand — hotels and restaurants in particular.

**Recommendation.** For California-specific analysis, or for hot-water-intensive building types in California, use `2025/comstock_amy2018_release_2` instead of Release 3.

Documented upstream at [ComStock: California Service Water Heating in 2025 Release 3](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/2025_release_3_ca_swh_known_issue.html). Recorded here because nothing in the OEDI repository itself signalled it — this is the **current** ComStock release.

---

### KI-007 · Upgrade packages 6 and 9 mislabelled — ComStock 2025 Release 2
**Severity:** Significant · **Affects results:** **Yes, via misinterpretation**
**Status: open — the incorrect names remain in the published metadata and annual results**

**Affected:** `2025/comstock_amy2018_release_2`, `2025/comstock_amy2012_release_2`

The results for **package 6 (Demand Flexibility)** and **package 9 (Geothermal Heat Pump)** were swapped. `upgrades_lookup.json` and `measure_name_crosswalk.csv` were subsequently corrected, but **the incorrect names persist in the metadata and annual results files published on OEDI** and in the Data Viewer.

An analyst reading package names directly from the results files will attribute geothermal heat pump savings to demand flexibility, and vice versa.

**Workaround.** Resolve package identity from `upgrades_lookup.json` and `measure_name_crosswalk.csv`, not from names embedded in the results files.

Fixed in `2025/comstock_amy2018_release_3`, **but the 2012 weather year was not re-released**, so `2025/comstock_amy2012_release_2` — the current release in its lineage — still carries it.

Documented upstream at [ComStock: Geothermal Heat Pump and Demand Flexibility Package Naming in 2025 Release 2](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/2025_release_2_packages_known_issue.html).

---

### KI-008 · Dead GitHub link in the current ComStock README
**Severity:** Caution · **Identified:** 2026-08-04 · **Affects results:** No
**Status: RESOLVED 2026-08-05 — the PDF is regenerated from the corrected Markdown, so both carry the working links**

**Affected:** `2025/comstock_amy2018_release_3`, `2025/resstock_amy2018_release_1`, `2025/resstock_amy2012_release_1`

The organization rename moved documentation URLs, and **five link targets in the current release READMEs were not updated**. All five return HTTP 404.

| Release | Dead URL | Correct URL |
|---|---|---|
| ComStock 2025 R3 | `github.com/NREL/ComStock/releases/tag/2025-3` | `github.com/NatLabRockies/ComStock/releases/tag/2025-3` |
| ResStock 2025 R1 | `nrel.github.io/…/assets/trd/ResStockTechnicalReferenceGuide_2025_1.pdf` (×2) | `natlabrockies.github.io/…/assets/trd/ResStockTechnicalReferenceGuide_2025_1.pdf` |
| ResStock 2025 R1 | `nrel.github.io/…/docs/FAQ.html` | `natlabrockies.github.io/…/docs/FAQ.html` |
| ResStock 2025 R1 | `nrel.github.io/…/explanations/One_Row_Data_House.html` | `natlabrockies.github.io/…/explanations/One_Row_Data_House.html` |
| ResStock 2025 R1 | `nrel.github.io/…/explanations/Why_at_Least_1000_Samples_is_Recommended.html` | `natlabrockies.github.io/…/explanations/**Number_of_samples.html**` — the page was also **renamed** |

The ResStock README applies to **both** 2025 ResStock releases, since they share one document.

Two things make this worse than a simple rename miss. The dead Technical Reference Guide link is the primary route to that document, and it appears twice. And in both documents the dead links sit **alongside working `natlabrockies.github.io` links** — the rename was applied partially, so nothing looked obviously broken.

Every replacement above has been fetched and confirmed correct. Full results in `deliverables/LINK_CHECK.md`.

---

### KI-009 · Release documentation does not match the directory
**Severity:** Caution · **Identified:** 2026-08-04 · **Affects results:** No
**Status: partially resolved — manifest.json now records the directories that actually exist; the README contents tables are unchanged**

**Affected:** `2025/resstock_amy2018_release_1`

The "OEDI Data Lake Contents" table in the release README does not list `comparisons/` or `timeseries_aggregates_new_env/`, both of which are present. It documents a `measure_name_crosswalk.csv`; the release ships `measure_name_crosswalk_res_2025_1.xlsx`.

The omission of `timeseries_aggregates_new_env/` is why KI-001 is hard to discover.

---

### KI-010 · `resstock_dataset_2024.1` is an anomalous release
**Severity:** Significant · **Identified:** 2026-08-04 · **Affects results:** No
**Status: open — blocked on locating the upgrade package crosswalk**

**Affected:** `2024/resstock_dataset_2024.1`

This is the one release in the repository that does not follow the standard conventions, and it should be treated as a special case rather than as a variant of the normal layout.

**It contains no timeseries data of any kind** — no `timeseries_aggregates/`, no `timeseries_individual_buildings/`, and no `building_energy_models/`. It is an annual-results-only release: 5.9 TB across 30,055 objects covering **260 upgrade packages**, comprising metadata, annual results by state and national, weather, and geographic information.

Three further deviations:

1. **No `upgrades_lookup.json`.** Upgrades are described in `Measure Package Index.csv` using decimal package numbers (`1.01`, `1.02`, … `15.28`). The data files use sequential integers (`upgrade1.parquet` … `upgrade260.parquet`). **No crosswalk between the two schemes is published**, so there is no way to determine which measure package `upgrade137.parquet` represents. The mapping cannot be reconstructed from the bucket.
2. **Non-standard nesting.** All content sits one level deeper than every other release, under `resstock_tmy3/`. Code that assumes `<year>/<release>/<directory>/` finds an empty release.
3. **A stale `UnderConstruction.txt`.** It states that all available data is up to date and ready to use, while promising building models "by May 3rd" with no year. **Those models were never uploaded and will not be** — the release is complete as published, and this notice is scheduled for deletion. Its absence of timeseries data and models is the defining characteristic of the release, not a gap awaiting completion.

**Workaround.** None for the upgrade numbering. Annual results and metadata are usable per-file, and the data dictionary is valid, but any analysis that needs to know *which measure* a file represents is blocked until the crosswalk is published.

---

### KI-011 · `resstock_amy2012_release_1` is missing four directories
**Severity:** Caution · **Identified:** 2026-08-04 · **Affects results:** No — affects availability
**Status: under investigation — may be intentional**

**Affected:** `2025/resstock_amy2012_release_1`

The release lacks `weather/`, `geographic_information/`, `building_energy_models/`, and `comparisons/`, all of which its sibling `2025/resstock_amy2018_release_1` provides. The two releases otherwise carry the same content apart from the weather year.

The `weather/` gap is the most consequential: **AMY 2012 weather is what distinguishes this release, and those files are not published anywhere else in the repository.**

**Workaround.** For `geographic_information/` and `building_energy_models/`, use `2025/resstock_amy2018_release_1` — those assets are not weather-dependent. There is currently no source for the AMY 2012 weather files within this repository.

---

### KI-012 · County-level aggregates may rest on very few models
**Severity:** Informational · **Affects results:** Interpretation
**Status: inherent — a property of small-sample geographies, not a defect to repair**

**Affected:** All releases offering county aggregates

In sparsely populated counties, the number of building models behind an aggregate may be in single digits, making the resulting load profile unrealistic. Check the `models_used` column before using any aggregate. To keep uncertainty near 15%, at least 1,000 individual dwelling models are recommended before drawing a conclusion. One row of data is not one dwelling unit or one household.

### KI-013 · The ComStock data dictionary does not join to its own data
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** No
**Status: **RESOLVED by this publication** — corrected dictionaries ship in this same change**

**Affected:** All ComStock releases from 2023 Release 2 onward

`data_dictionary.tsv` records `field_name` **without** the trailing `..unit` suffix that the Parquet columns actually carry. The data has `in.sqft..ft2`; the dictionary documents `in.sqft`. ResStock dictionaries record the full column name, so the same code works for ResStock and fails for ComStock.

```python
# fails for ComStock, succeeds for ResStock
dd = pd.read_csv("data_dictionary.tsv", sep="\t")
df = pd.read_parquet(annual_results)
documented = df.columns.isin(dd.field_name)     # mostly False for ComStock
```

**Workaround.** Strip the suffix before joining:

```python
df.columns.str.replace(r"\.\.[^.]+$", "", regex=True).isin(dd.field_name)
```

A corrected dictionary, with `field_name` matching the Parquet schema exactly, is proposed for each affected release. 4,679 field names were corrected across 7 releases, every one derived from the release's own Parquet schema rather than inferred.

### KI-014 · The ComStock 2025 Release 2 dictionary describes the previous generation
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** No
**Status: open — needs an author who knows the intent behind the renames**

**Affected:** `2025/comstock_amy2018_release_2`, `2025/comstock_amy2012_release_2`, `2025/comstock_amy2018_release_1`

Separate from KI-013 and still present after that correction. The dictionary documents **402 fields that do not exist** in the release's annual results, and leaves **348 actual columns undocumented**. The cause is renaming: it still carries the previous generation's names, for example `out.qoi.maximum_daily_peak_intensity_apr` where the data has `out.qoi.maximum_daily_peak_apr..kw`.

Three releases are affected rather than one:

- `2025/comstock_amy2018_release_2` — where it originates.
- `2025/comstock_amy2012_release_2` — carries the same dictionary and is **current** in its lineage, because the 2012 weather year was never re-released with the Release 3 corrections.
- `2025/comstock_amy2018_release_1` — ships no dictionary at all, and the proposed sibling copy comes from Release 2 (KI-003), so it inherits the problem.

`2025/comstock_amy2018_release_3` shipped a corrected dictionary and is nearly exact against its data. Until Release 2 is corrected, resolve ComStock 2025 R2 column meanings from the **Release 3** dictionary where the column names match.

### KI-015 · `weight` and `applicability.*` are undocumented in ComStock 2025
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** Interpretation
**Status: open — needs one dictionary row per column**

**Affected:** All four 2025 ComStock releases

The annual results carry a `weight` column and one `applicability.<measure>` column per upgrade measure. Neither appears in any dictionary.

`weight` matters most: it is the number of real buildings a model represents, and it is required to scale any per-model result to the building stock. Summing an unweighted column across models gives a number that looks plausible and is wrong. Treat `weight` as required in every stock-level aggregation.

### KI-016 · 82 result columns were omitted from the AMY 2018 release
**Severity:** Caution · **Identified:** 2026-08-05 · **Affects results:** No
**Status: will not be changed — the AMY 2018 release cannot be regenerated**

**Affected:** `2025/resstock_amy2018_release_1` (columns missing), `2025/resstock_amy2012_release_1` (columns present but undocumented)

The two releases do not publish the same annual-results columns:

| Release | Annual-results columns |
|---|---|
| `2025/resstock_amy2018_release_1` | 771 |
| `2025/resstock_amy2012_release_1` | 853 |

`amy2012` is a strict superset. The 82 extra columns are:

| Group | Columns | Example |
|---|---|---|
| Component loads | 40 | `out.component_load.cooling.ceilings..kwh` |
| Component load savings | 40 | `out.component_load_savings.cooling.ceilings..kwh` |
| Heat-pump backup delivered load | 2 | `out.load.heating_hp_bkup.energy_delivered..kbtu` |

**This is a publication gap, not a modelling difference.** Both releases come from the same ResStock code version, with the same model creation and the same simulations. The columns were unintentionally omitted from the AMY 2018 release rather than added to the AMY 2012 one.

**The gap is permanent.** `2025/resstock_amy2018_release_1` cannot be regenerated, so these columns will never be published there. This is settled, not pending.

What that means in practice:

- **Every column present in both releases is directly comparable.** Differencing AMY 2012 against AMY 2018 to isolate a weather effect is sound — the underlying models are identical. The omission does not compromise anything you can currently read from either release.
- **There is no source for component loads on 2018 weather in this repository.** `2025/resstock_amy2012_release_1` holds the same models under 2012 weather. Whether that substitutes depends on your use case; it is not equivalent, and no equivalent exists here.
- **The 82 columns are not described in either data dictionary**, so they are undocumented even in the release that publishes them. Correcting that is a dictionary edit and does not depend on anything above — tracked as H-9 in the review's hygiene backlog, which is internal to the review and not published in this repository.

### KI-017 · The ResStock 2025 enumeration dictionary is not UTF-8
**Severity:** Caution · **Identified:** 2026-08-05 · **Affects results:** No
**Status: **RESOLVED by this publication** — the standardized dictionary shipping in this change is UTF-8**

**Affected:** `2025/resstock_amy2018_release_1`

`enumeration_dictionary.tsv` (6.1 MB) contains cp1252 non-breaking spaces and raises `UnicodeDecodeError` when opened with default settings. Every other dictionary in the repository decodes as UTF-8, so nothing signals that this one is different.

```python
pd.read_csv("enumeration_dictionary.tsv", sep="\t", encoding="cp1252")
```

### KI-018 · The ResStock 2025 README defines `amy2012` as 2018 weather
**Severity:** Caution · **Identified:** 2026-08-05 · **Affects results:** No
**Status: RESOLVED 2026-08-05 — the PDF is regenerated from the corrected Markdown**

**Affected:** `2025/resstock_amy2018_release_1`, `2025/resstock_amy2012_release_1`

The naming-convention section reads *"amy2012 = actual meteorological year 2018 (2018 weather data from NOAA ISD, NSRDB, and MesoWest)"* — a duplicate of the `amy2018` line above it. `amy2012` means actual meteorological year **2012**. The README is shared by both 2025 ResStock releases, so this is the definitional statement for the AMY 2012 release. The equivalent ComStock README states 2012 correctly.

---

### KI-031 · 215 occupancy schedule files are empty
**Severity:** Caution · **Identified:** 2026-08-05 · **Affects results:** No
**Status: will not be changed — the 2021 releases are archived and will not be re-uploaded**

**Affected:** `2021/resstock_amy2018_release_1` (210 files), `2021/resstock_tmy3_release_1` (5 files)

215 files under `occupancy_schedules/` are zero bytes, against a median size of about 240 KB for the rest of the directory. All were written on the same day. **This is the signature of an interrupted upload** — in this publication process a zero-byte object at an otherwise valid key means the content never arrived, not that the building has no schedule.

It is a small share — 210 of 549,800 objects in the AMY2018 directory, 0.04% — but that is high enough that a bulk job over the directory will hit them. Depending on the reader, an empty `.csv.gz` raises a decompression error or returns an empty frame that silently reduces your sample.

```python
obj = s3.get_object(Bucket=B, Key=key)
if obj["ContentLength"] == 0:
    continue          # known-empty schedule, not a key-construction error
```

**They are deliberately not deleted.** The key is documented and the building exists in the metadata, so an empty file is an honest record of a missing schedule. Replacing it with a 404 would look like a key-construction mistake and send a consumer hunting for a bug in their own code.

Every affected key is listed in `deliverables/ZERO_BYTE_OBJECTS.md`.

---

<!-- BEGIN UPSTREAM (generated) -->
## Summarised from the ResStock and ComStock known-issue pages

These are **summaries**. The authoritative text, with magnitudes, per-state
breakdowns and worked workarounds, is on the linked page — follow it before
acting on any of them. They are reproduced here because a consumer working from
S3 has no path to those pages, and several affect published results.

Two upstream issues are written out in full earlier in this file, because they affect a current release and were found during the review: KI-006, KI-007.

Upstream listings: [ResStock](https://natlabrockies.github.io/ResStock.github.io/docs/resources/resources.html#resstock-limitations-and-known-issues) · [ComStock](https://natlabrockies.github.io/ComStock.github.io/docs/resources/resources.html#known-issues)

### KI-019 · ResStock 2025 Release 1 Electric Panel Capacity
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** `2025/resstock_amy2018_release_1`, `2025/resstock_amy2012_release_1`

Electric panel capacity outputs are WRONG where an HVAC measure is a like-for-like replacement: the NEC load calculation counts the replacement as a new load, so panel constraints are overstated. Seven capacity columns are affected, across measures covering most of the stock. Do not use those columns for these measures.

[Full detail upstream](https://natlabrockies.github.io/ResStock.github.io/docs/resources/explanations/Issue_2025_1_Electric_Panel_Capacity.html)

---

### KI-020 · ResStock 2025 Release 1 Column Applicability
**Severity:** Caution · **Identified:** 2026-08-05 · **Affects results:** No
**Status: Open**

**Affected:** `2025/resstock_amy2018_release_1`, `2025/resstock_amy2012_release_1`

Three upgrade.* columns are populated for only some of the upgrades they should cover: upgrade.heating_fuel, upgrade.hvac_heating_type_and_fuel and upgrade.hvac_detailed_performance_data. The values present are correct; values are missing rather than wrong, and can be inferred from other columns.

[Full detail upstream](https://natlabrockies.github.io/ResStock.github.io/docs/resources/explanations/Issue_2025_1_Column_Applicability.html)

---

### KI-021 · ResStock 2024 Release 2 Electricity and Energy Bills
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** `2024/resstock_amy2018_release_2`, `2024/resstock_tmy3_release_2`

Electricity and energy bills were computed from three different rate sets, so bills are internally inconsistent and bill SAVINGS can be nonsensical -- a bill can rise while consumption falls. Savings are affected more than absolute bills. Gas, propane and oil bills are unaffected. Upstream gives a recalculation procedure.

[Full detail upstream](https://natlabrockies.github.io/ResStock.github.io/docs/resources/explanations/Issue_2024_2_Electricity_and_Energy_Bills.html)

---

### KI-022 · ResStock 2024 Release 2 Measure Applicability
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** `2024/resstock_amy2018_release_2`, `2024/resstock_tmy3_release_2`

Dual-fuel heat pump measures (upgrades 4, 9 and 14) are marked not-applicable for a subset of models that should have received them, so their upgrade results equal the baseline. Roughly 2% of models nationally, varying widely by state.

[Full detail upstream](https://natlabrockies.github.io/ResStock.github.io/docs/resources/explanations/Issue_2024_2_Measure_Applicability.html)

---

### KI-023 · Wall Type Issue, Especially in Maine
**Severity:** Caution · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** 13 releases — see `known_issue_ids` in `catalog.json`

Maine wall types are mis-characterised in the source assessor data, showing far more masonry and far less wood framing than local experts expect. Affects wall type, wall exterior finish, and the applicability of measures that require wood-frame walls. Energy results are believed little affected. Applies to ALL published ResStock datasets.

[Full detail upstream](https://natlabrockies.github.io/ResStock.github.io/docs/resources/explanations/Issue_Wall_Type_Especially_Maine.html)

---

### KI-024 · California Models Known Issues
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** 7 releases — see `known_issue_ids` in `catalog.json`

California warehouse models have no conditioned HVAC system, though their metadata implies one, so heating, cooling and ventilation energy is understated for that segment -- along with the emissions and bills derived from it.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/california_known_issues.html)

---

### KI-025 · California Models Known Issues
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** 6 releases — see `known_issue_ids` in `catalog.json`

California models use older DEER equipment assumptions with much higher plug and process loads than the rest of the country, which overstates interior equipment consumption and its share of savings potential. See detail_url for the magnitude by building type.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/california_known_issues.html)

---

### KI-026 · California Models Known Issues
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Will not be changed**

**Affected:** 4 releases — see `known_issue_ids` in `catalog.json`

California models summed Title 24 ventilation requirements instead of taking the maximum, roughly doubling ventilation rates and inflating heating and cooling intensity. Corrected before ComStock 2024 Release 1.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/california_known_issues.html)

---

### KI-027 · 2024 Release 2: Utility Bill and Emissions
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** `2024/comstock_amy2018_release_2`

The sampling method reuses models across locations, and utility rates and grid emissions factors from the original location were carried over rather than re-applied for the reallocated one. Affects 19 utility bill fields and 200+ emissions fields. Upstream advises not using utility bills from the aggregate files at all.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/utility_bills_emissions_known_issue.html)

---

### KI-028 · 2024 Release 2: Metadata and Annual Results Aggregate File Discrepancy
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Open**

**Affected:** `2024/comstock_amy2018_release_2`

The metadata_and_annual_results_aggregates files were built from two different weight tables, so aggregates disagree between geographic levels -- national totals differ by up to about 5% between county and state aggregation. Neither group is more correct; each is internally consistent.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/aggregate_file_discrepancy_known_issue.html)

---

### KI-029 · 2025 Release 2: Hawaii AMY2012 Weather Files
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** **Yes**
**Status: Will not be changed**

**Affected:** `2025/comstock_amy2012_release_2`

The AMY2012 weather files for Hawaii contain temperatures below freezing, which does not occur there. Every Hawaii model is affected and state heating energy is materially overstated relative to the 2018 weather releases. Upstream recommends NOT using this dataset for Hawaii analysis.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/2025_release_2_hi_known_issue.html)

---

### KI-030 · 2025 Release 3: Heat Pump and Envelope Package Naming
**Severity:** Significant · **Identified:** 2026-08-05 · **Affects results:** No
**Status: Will not be changed**

**Affected:** `2025/comstock_amy2018_release_3`

The names of packages pkg_0003 and pkg_0004 are swapped: data labelled as one holds the results of the other. The results themselves are correct and only the label is wrong, but in.upgrade_name in the published metadata and annual results cannot be corrected. Resolve package identity from upgrades_lookup.json and measure_name_crosswalk.csv.

[Full detail upstream](https://natlabrockies.github.io/ComStock.github.io/docs/resources/explanations/2025_release_3_packages_known_issue.html)

---

<!-- END UPSTREAM -->

## Resolved and historical

### KI-100 · Kiva foundation model bug
**Severity:** Significant · **Identified:** 2024-03-26 · **Affects results:** **Yes**
**Status: will not be changed — fixed in the code for later releases, but the affected 2022 data is still published and will not be regenerated**

**Affected:** `2022/resstock_amy2012_release_1`, `2022/resstock_amy2012_release_1.1`, `2022/resstock_amy2018_release_1`, `2022/resstock_amy2018_release_1.1`, `2022/resstock_tmy3_release_1`, `2022/resstock_tmy3_release_1.1`

During the transition to OpenStudio-HPXML v1.5.0, OpenStudio 3.5.0, and EnergyPlus 22.2, a bug in the Kiva foundation model was identified and fixed. The fix improves foundation heat transfer by setting better initial temperature conditions based on foundation type and insulation level.

The bug was present in the code that generated the six releases above. It affects both baseline and upgrade simulations, and is most apparent in about **11% of models**, where the foundation slab temperature initial condition differs between the baseline and the upgrade run. It affects heating and cooling energy early in the year, since HVAC loads depend on foundation temperature and heat transfer rates.

**Consequence.** Those simulations show **unexpected savings values**, because slab heat transfer differs between baseline and upgrade even though the upgrade should not have affected it.

**Recommendation.** For savings analysis, use a later ResStock release. Fixed in all releases from 2024 onward.

### 2022-06-07 · Energy use intensity in residential individual timeseries
Corrected in the residential AMY2018 and TMY3 individual building timeseries files. Earlier results did not have unit conversions correctly applied.

### 2022-06-02 · Residential demand results
Corrected in the residential AMY2018 and TMY3 `metadata.parquet` and `metadata.tsv`. Earlier results were a factor of four too high.

### 2022-03-07 · Commercial aggregates and units
Corrected all commercial aggregates in the AMY2018 and TMY3 datasets, where some end uses were blank and end-use totals therefore did not match fuel totals. Corrected units in the commercial `data_dictionary.tsv`; all energy consumption is in kWh. Corrected total site energy consumption from million Btu to kWh.

---

## Reporting an issue

ResStock: `ResStock@nlr.gov` · ComStock: `ComStock@nlr.gov`