Add troubleshooting guide for AI-For-Beginners

troubleshoot.md

@@ -0,0 +1,273 @@
+# AI-For-Beginners Troubleshooting Guide
+
+This guide helps you resolve common issues encountered while using or contributing to the [AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners) repository. Each problem includes background, symptoms, explanations, and step-by-step solutions.
+
+---
+
+## Table of Contents
+
+- [General Issues](#general-issues)
+- [Installation Issues](#installation-issues)
+- [Configuration Issues](#configuration-issues)
+- [Running Notebooks](#running-notebooks)
+- [Performance Problems](#performance-problems)
+- [Textbook Website Problems](#textbook-website-problems)
+- [Contributing Issues](#contributing-issues)
+- [FAQ](#faq)
+- [Getting Help](#getting-help)
+
+---
+
+## General Issues
+
+### 1. Repository Not Cloning Properly
+
+**Background:** Cloning allows you to copy the repository to your machine.
+
+**Symptoms:**
+- Error: `fatal: repository not found`
+- Error: `Permission denied (publickey)`
+
+**Possible Causes:**
+- Incorrect repository URL
+- Insufficient permissions
+- SSH keys not configured
+
+**Solutions:**
+1. **Check the repository URL.**  
+   Use the HTTPS URL:  
+   ```
+   git clone https://github.com/microsoft/AI-For-Beginners.git
+   ```
+2. **Switch to HTTPS if SSH fails.**  
+   If you see `Permission denied (publickey)`, use the HTTPS link above instead of SSH.
+3. **Configure SSH keys (optional).**  
+   If you want to use SSH, follow [GitHub's SSH guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+---
+
+## Installation Issues
+
+### 2. Python Environment Issues
+
+**Background:** The repository relies on Python and various libraries.
+
+**Symptoms:**
+- Error: `ModuleNotFoundError: No module named '<package>'`
+- Import errors when running scripts or notebooks
+
+**Possible Causes:**
+- Dependencies not installed
+- Wrong Python version
+
+**Solutions:**
+1. **Set up a virtual environment.**  
+   ```bash
+   python -m venv venv
+   source venv/bin/activate   # On Windows: venv\Scripts\activate
+   ```
+2. **Install dependencies.**  
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. **Check Python version.**  
+   Use Python 3.7 or newer.  
+   ```bash
+   python --version
+   ```
+
+### 3. Jupyter Not Installed
+
+**Background:** Notebooks are a core learning resource.
+
+**Symptoms:**
+- Error: `jupyter: command not found`
+- Notebooks fail to launch
+
+**Possible Causes:**
+- Jupyter not installed
+
+**Solutions:**
+1. **Install Jupyter Notebook.**  
+   ```bash
+   pip install notebook
+   ```
+   or, if using Anaconda:
+   ```bash
+   conda install notebook
+   ```
+2. **Start Jupyter Notebook.**  
+   ```bash
+   jupyter notebook
+   ```
+
+### 4. Dependency Version Conflicts
+
+**Background:** Projects can break if package versions are mismatched.
+
+**Symptoms:**
+- Errors or warnings about incompatible versions
+
+**Possible Causes:**
+- Old or conflicting Python packages
+
+**Solutions:**
+1. **Install in a clean environment.**  
+   Delete old venv/conda env and create a new one.
+2. **Use exact versions.**  
+   Always run:
+   ```bash
+   pip install -r requirements.txt
+   ```
+   If this fails, manually install missing packages as described in README.
+
+---
+
+## Configuration Issues
+
+### 5. Environment Variables Not Set
+
+**Background:** Some modules may require keys, tokens, or config settings.
+
+**Symptoms:**
+- Error: `KeyError` or warnings about missing configuration
+
+**Possible Causes:**
+- Required environment variables not set
+
+**Solutions:**
+1. **Check for `.env.example` or similar files.**
+2. **Create a `.env` file and fill in required values.**
+3. **Reload your terminal or IDE after setting environment variables.**
+
+---
+
+## Running Notebooks
+
+### 6. Notebook Will Not Open or Run
+
+**Background:** Jupyter notebooks need proper setup.
+
+**Symptoms:**
+- Notebook fails to launch
+- Browser not opening automatically
+
+**Possible Causes:**
+- Jupyter not installed
+- Browser configuration issues
+
+**Solutions:**
+1. **Install Jupyter (see Installation Issues above).**
+2. **Open notebooks manually.**
+   - Copy the URL from terminal (e.g., `http://localhost:8888/?token=...`) and paste it into your browser.
+
+### 7. Kernel Crashing or Freezing
+
+**Background:** Notebook kernels can crash due to resource limits or code errors.
+
+**Symptoms:**
+- Kernel dies or restarts repeatedly
+- Out-of-memory errors
+
+**Possible Causes:**
+- Large datasets
+- Incompatible code or packages
+
+**Solutions:**
+1. **Restart the kernel.**  
+   Use the "Restart Kernel" button in Jupyter.
+2. **Check memory usage.**  
+   Close unused applications.
+3. **Run notebooks on cloud platforms.**  
+   Use [Google Colab](https://colab.research.google.com/) or [Azure Notebooks](https://notebooks.azure.com/).
+
+---
+
+## Performance Problems
+
+### 8. Notebooks Running Slowly
+
+**Background:** Some AI tasks require significant memory and CPU.
+
+**Symptoms:**
+- Slow execution
+- Laptop fan running loudly
+
+**Possible Causes:**
+- Large datasets or models
+- Limited system resources
+
+**Solutions:**
+1. **Use a cloud platform.**
+   - Upload notebook to Colab or Azure Notebooks.
+2. **Reduce dataset size.**
+   - Use sample data for practice.
+3. **Close unnecessary programs.**
+   - Free up system RAM.
+
+---
+
+## Textbook Website Problems
+
+### 9. Chapter Not Loading
+
+**Background:** The online textbook displays lessons and chapters.
+
+**Symptoms:**
+- A chapter (e.g., Transformers/BERT) is missing or not opening
+
+**Known Issue:**  
+- [Issue #303](https://github.com/microsoft/AI-For-Beginners/issues/303): “18 Transformers. BERT. can't be opened on the textbook website.” Caused by a filename error (`READMEtransformers.md` instead of `README.md`).
+
+**Solutions:**
+1. **Check for file renaming errors.**  
+   If you’re a contributor, ensure chapter files are named `README.md`.
+2. **Report missing files.**  
+   Open a GitHub issue with the chapter name and error details.
+
+---
+
+## Contributing Issues
+
+### 10. PR Not Accepted or Builds Failing
+
+**Background:** Contributions must pass tests and follow guidelines.
+
+**Symptoms:**
+- Pull request rejected
+- CI/CD pipeline errors
+
+**Possible Causes:**
+- Failing tests
+- Not following coding standards
+
+**Solutions:**
+1. **Read the contribution guidelines.**
+   - Follow the repository’s [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md).
+2. **Run tests locally before pushing.**
+3. **Check for linting rules or formatting requirements.**
+
+---
+
+## FAQ
+
+### Where can I find help for specific modules?
+- Each module usually has its own README. Start there for setup and usage tips.
+
+### How do I report a bug or request a feature?
+- [Open a GitHub Issue](https://github.com/microsoft/AI-For-Beginners/issues/new) with a clear description and steps to reproduce.
+
+### Can I ask for help if my problem isn’t listed?
+- Yes! Search existing issues first, and if you don’t find your problem, create a new issue.
+
+---
+
+## Getting Help
+
+- **Check Issues:** [GitHub Issues](https://github.com/microsoft/AI-For-Beginners/issues)
+- **Ask Questions:** Use GitHub Discussions or open an issue.
+- **Community:** See repository links for chat/forum options.
+
+---
+
+_Last Updated: 2025-09-20_