Troubleshooting
===============

Common Issues and Solutions
---------------------------

Installation Issues
~~~~~~~~~~~~~~~~~~~

**Problem: "ModuleNotFoundError" when importing humancompatible-train**

Solution:
   1. Verify installation: ``pip list | grep humancompatible-train``
   2. Reinstall the package: ``pip install --upgrade humancompatible-train``
   3. Check your Python version: ``python --version`` (requires Python 3.8+)

**Problem: "Permission denied" during installation**

Solution:
   Use a virtual environment (recommended):
   
   .. code-block:: bash
   
      python -m venv venv
      source venv/bin/activate  # On Windows: venv\Scripts\activate
      pip install humancompatible-train

Training Issues
~~~~~~~~~~~~~~~

**Problem: Constraints are not being satisfied**

Solutions:
   1. Verify constraint definitions are correct
   2. Check that constraints are compatible with your data
   3. Increase training time or adjust hyperparameters
   4. Review constraint priorities and weights

**Problem: Out of memory during training**

Solutions:
   1. Reduce batch size
   2. Use a smaller dataset for testing
   3. Enable gradient checkpointing if available
   4. Consider distributed training

Performance Issues
~~~~~~~~~~~~~~~~~~

**Problem: Training is very slow**

Solutions:
   1. Profile your code to identify bottlenecks
   2. Use fewer constraints if possible
   3. Optimize your data loading pipeline
   4. Consider using GPU acceleration
   5. Try reducing dataset size for experimentation

Getting More Help
-----------------

If you can't find a solution here:

1. Check the :doc:`support` page for contact information
2. Review the :doc:`API Reference <examples/api_reference>` for function signatures
3. Open an issue on the GitHub repository
4. Consult the project's issue tracker for similar problems

FAQ
---

**Q: Which Python versions are supported?**

A: Python 3.8 and higher. We recommend using Python 3.9 or later.

.. **Q: Can I use my custom model architecture?**

.. A: Yes, see the :doc:`Advanced Usage <examples/advanced_usage>` section for details on custom constraints and models.

**Q: How do I report a bug?**

A: Please open an issue on GitHub with:
   
   - Description of the problem
   - Steps to reproduce
   - Python version and environment information
   - Relevant code snippets or error messages