8000
Skip to content

troubleshoot.md

Latest commit

 

History

History
273 lines (195 loc) · 6.94 KB

troubleshoot.md

File metadata and controls

273 lines (195 loc) · 6.94 KB

AI-For-Beginners Troubleshooting Guide

This guide helps you resolve common issues encountered while using or contributing to the AI-For-Beginners repository. Each problem includes background, symptoms, explanations, and step-by-step solutions.

Table of Contents

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.

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. 
    python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
  2. Install dependencies. 
    pip install -r requirements.txt
  3. Check Python version.
    Use Python 3.7 or newer. 
    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. 
    pip install notebook
    or, if using Anaconda: 
    conda install notebook
  2. Start Jupyter Notebook. 
    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: 
    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 or Azure Notebooks.

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: “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.
  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?

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
  • Ask Questions: Use GitHub Discussions or open an issue.
  • Community: See repository links for chat/forum options.

Last Updated: 2025-09-20
0