# Troubleshooting

This page collects common issues and their causes, based on how `mobts` actually behaves. If something here doesn't resolve your issue, check the [Configuration](configuration.md) page for the specific thresholds involved.

## My timestamps look wrong / shifted

`mobts` parses timestamp strings with `utc=True`, which **treats naive (timezone-less) input as if it were already UTC**, rather than converting it from local time. If your source data is in local time (e.g. Paris time) and doesn't already carry timezone information, convert it to UTC yourself before passing it in, or your timestamps will be silently mislabeled rather than converted.

## I have duplicate rows for the same counter and timestamp

`mobts` sorts by counter and timestamp during formatting, but doesn't detect or remove exact duplicate `(counter, timestamp)` pairs. Duplicates will pass through and can distort correlation calculations, pivot tables, and STL grouping downstream. Check for and resolve duplicates in your input data before running either stage.

## Saving both reports overwrote one of them

`pp.report()` and `imp.report()` both default to `filepath='preprocess_report.txt'`. If you save both with `save=True` and don't pass an explicit `filepath` to each, the second call will overwrite the first. Always pass distinct filenames:

```python
pp.report(save=True, filepath='preprocess_report.txt')
imp.report(save=True, filepath='imputation_report.txt')
```

## A counter didn't get imputed with the method I expected

Donor-based methods (regression, scaled median) require enough historical overlap and coverage with eligible donor counters, governed by `DonorsConfig`'s thresholds (see [Configuration](configuration.md)). A counter that does not meet these thresholds falls back to the next method in the priority order, ultimately to STL if no donors qualify. This is expected behavior, not a bug. Check `imp.report()`'s method-count breakdown to see how many counters used each method.

## A counter disappeared from my output entirely

Two likely causes:

- **Sparsity** — a counter with a missing-value rate above `SparsityConfig.sparse_threshold` (default `0.5`) is dropped entirely before scoring or imputation.
- **Missing counter name** — rows where the counter identifier itself is `NaN` are dropped during formatting, regardless of how much valid count data they have.

Check `pp.report()`'s counter counts to see whether either of these accounts for the discrepancy.

## Calling `.report()` raises a `ValueError`

Both `preprocess` and `impute` require `.run()` to be called at least once before `.report()` — it raises a clear `ValueError` if no run has happened yet. This isn't a crash; call `.run()` first.

## My metadata columns show unexpected or missing values

See the note in [Pipeline notes](pipeline_notes.md#passing-metadata-columns-through). `metadata_cols` assumes one constant value per counter. If a column's real value varies by timestamp for the same counter, only one arbitrary value is kept and applied across every row for that counter.