Add troubleshooting section to readme file

README.md

@@ -309,3 +309,145 @@ spaces_before_comment = 2
 ```
 
 Please run `yapf --in-place --recursive <filename>` on all affected files.
+
+## Troubleshooting
+
+### Installation Issues
+
+#### ARM/Apple Silicon Compatibility
+**Problem:** `lingvo` dependency fails on Apple Silicon (M1/M2/M3) machines.
+```
+ERROR: Could not build wheels for lingvo
+```
+**Solution:** This is a known issue. The `lingvo` dependency doesn't support ARM architectures. We recommend:
+- Use x86_64 emulation via Rosetta 2: `arch -x86_64 pip install timesfm[pax]`
+- Use the PyTorch version instead, which has better ARM support: `pip install timesfm[torch]`
+- Use Docker with x86_64 emulation for consistent environments
+
+#### Memory Issues During Installation
+**Problem:** Installation fails with memory errors.
+```
+Killed (signal 9)
+```
+**Solution:** 
+- Ensure at least 32GB RAM is available
+- Close other applications during installation
+- Use `pip install --no-cache-dir timesfm[torch]` to reduce memory usage
+- Install in a clean virtual environment
+
+#### JAX/PyTorch Version Conflicts
+**Problem:** Conflicting JAX and PyTorch installations.
+```
+ImportError: cannot import name 'jax' from 'jax'
+```
+**Solution:**
+- For PyTorch-only usage: `pip install timesfm[torch]`
+- For covariates with PyTorch: `pip install timesfm[torch] && pip install jax jaxlib`
+- For PAX version: `pip install timesfm[pax]`
+
+### Runtime Errors
+
+#### Model Loading Issues
+**Problem:** Checkpoint download fails or is corrupted.
+```
+HfFileNotFoundError: 404 Client Error
+```
+**Solution:**
+- Check internet connectivity
+- Verify Hugging Face Hub access: `huggingface-cli login`
+- Clear cache: `rm -rf ~/.cache/huggingface/`
+- Use explicit checkpoint paths if needed
+
+#### CUDA/GPU Issues
+**Problem:** GPU not detected or CUDA errors.
+```
+RuntimeError: CUDA out of memory
+```
+**Solutions:**
+- Reduce `per_core_batch_size` (try 16, 8, or 4)
+- Reduce `context_len` to minimum needed
+- Use `backend="cpu"` for testing
+- Check GPU memory: `nvidia-smi`
+
+#### Context Length Errors
+**Problem:** Input series longer than model capacity.
+```
+ValueError: context_len must be <= 512 for v1.0 models
+```
+**Solutions:**
+- Use TimesFM-2.0 for longer contexts (up to 2048)
+- Ensure `context_len` is multiple of 32
+- Truncate input series if necessary
+- Set appropriate `context_len` in model initialization
+
+### Data Issues
+
+#### Frequency Mapping Problems
+**Problem:** Unexpected forecasting results with wrong frequency.
+```
+Warning: Frequency 'D' mapped to category 0
+```
+**Solutions:**
+- Verify frequency mapping: D→0 (high), W/M→1 (medium), Q/Y→2 (low)
+- Override automatic mapping by specifying frequency manually
+- Check data granularity matches chosen frequency category
+
+#### Missing Values in Time Series
+**Problem:** NaN or missing values in input data.
+```
+ValueError: Input contains NaN values
+```
+**Solutions:**
+- Pre-process data to handle missing values (forward fill, interpolation)
+- Ensure continuous time series without gaps
+- Remove or impute missing values before forecasting
+
+#### Covariate Dimension Mismatches
+**Problem:** Covariate lengths don't match forecast horizon.
+```
+ValueError: Dynamic covariates must cover context + horizon
+```
+**Solutions:**
+- Ensure dynamic covariates have length = context + horizon
+- Check static vs dynamic covariate classification
+- Verify covariate data alignment with time series
+
+### Performance Issues
+
+#### Slow Inference
+**Problem:** Forecasting takes unexpectedly long.
+**Solutions:**
+- Use GPU backend: `backend="gpu"`
+- Optimize batch size: increase `per_core_batch_size`
+- Use appropriate model size for your use case
+- Profile with smaller data first
+
+#### Memory Usage
+**Problem:** High memory consumption during inference.
+**Solutions:**
+- Reduce batch size: `per_core_batch_size=1`
+- Process data in chunks
+- Use smaller context length when possible
+- Monitor memory with `htop` or `nvidia-smi`
+
+### Common Error Messages
+
+#### `ModuleNotFoundError: No module named 'xreg_lib'`
+**Cause:** Missing JAX dependencies for covariates functionality.
+**Solution:** `pip install jax jaxlib`
+
+#### `ValueError: horizon_len must be positive`
+**Cause:** Invalid horizon length specified.
+**Solution:** Set `horizon_len > 0` in model initialization.
+
+#### `RuntimeError: Expected input batch_size (X) to be divisible by batch_size (Y)`
+**Cause:** Batch size mismatch.
+**Solution:** Adjust `per_core_batch_size` or input data batching.
+
+### Getting Help
+
+If you encounter issues not covered here:
+1. Check the [GitHub Issues](https://github.com/google-research/timesfm/issues)
+2. Review the [notebooks/](notebooks/) for working examples
+3. Verify your installation follows the exact steps in the Installation section
+4. Test with the provided example data before using your own datasets