GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/AI-For-Beginners

Public

mirrored fromhttps://github.com/microsoft/AI-For-BeginnersAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
main

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

AI-For-Beginners/translations/en

translations/en/troubleshoot.md

287lines · modecode

RawDownload
Latest commit unavailable.
1<!--
2CO_OP_TRANSLATOR_METADATA:
3{
4 "original_hash": "8d9c5a4a7c7798d699672a22cb7fea86",
5 "translation_date": "2025-10-03T09:33:29+00:00",
6 "source_file": "troubleshoot.md",
7 "language_code": "en"
8}
9-->
10# AI-For-Beginners Troubleshooting Guide
11
12This 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.
13
14---
15
16## Table of Contents
17
18- [General Issues](../..)
19- [Installation Issues](../..)
20- [Configuration Issues](../..)
21- [Running Notebooks](../..)
22- [Performance Problems](../..)
23- [Textbook Website Problems](../..)
24- [Contributing Issues](../..)
25- [FAQ](../..)
26- [Getting Help](../..)
27
28---
29
30## General Issues
31
32### 1. Repository Not Cloning Properly
33
34**Background:** Cloning allows you to copy the repository to your machine.
35
36**Symptoms:**
37- Error: `fatal: repository not found`
38- Error: `Permission denied (publickey)`
39
40**Possible Causes:**
41- Incorrect repository URL
42- Insufficient permissions
43- SSH keys not configured
44
45**Solutions:**
461. **Check the repository URL.**
47 Use the HTTPS URL:
48 ```
49 git clone https://github.com/microsoft/AI-For-Beginners.git
50 ```
512. **Switch to HTTPS if SSH fails.**
52 If you see `Permission denied (publickey)`, use the HTTPS link above instead of SSH.
533. **Configure SSH keys (optional).**
54 If you want to use SSH, follow [GitHub's SSH guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
55
56---
57
58## Installation Issues
59
60### 2. Python Environment Issues
61
62**Background:** The repository relies on Python and various libraries.
63
64**Symptoms:**
65- Error: `ModuleNotFoundError: No module named '<package>'`
66- Import errors when running scripts or notebooks
67
68**Possible Causes:**
69- Dependencies not installed
70- Wrong Python version
71
72**Solutions:**
731. **Set up a virtual environment.**
74 ```bash
75 python -m venv venv
76 source venv/bin/activate # On Windows: venv\Scripts\activate
77 ```
782. **Install dependencies.**
79 ```bash
80 pip install -r requirements.txt
81 ```
823. **Check Python version.**
83 Use Python 3.7 or newer.
84 ```bash
85 python --version
86 ```
87
88### 3. Jupyter Not Installed
89
90**Background:** Notebooks are a core learning resource.
91
92**Symptoms:**
93- Error: `jupyter: command not found`
94- Notebooks fail to launch
95
96**Possible Causes:**
97- Jupyter not installed
98
99**Solutions:**
1001. **Install Jupyter Notebook.**
101 ```bash
102 pip install notebook
103 ```
104 or, if using Anaconda:
105 ```bash
106 conda install notebook
107 ```
1082. **Start Jupyter Notebook.**
109 ```bash
110 jupyter notebook
111 ```
112
113### 4. Dependency Version Conflicts
114
115**Background:** Projects can break if package versions are mismatched.
116
117**Symptoms:**
118- Errors or warnings about incompatible versions
119
120**Possible Causes:**
121- Old or conflicting Python packages
122
123**Solutions:**
1241. **Install in a clean environment.**
125 Delete old venv/conda env and create a new one.
1262. **Use exact versions.**
127 Always run:
128 ```bash
129 pip install -r requirements.txt
130 ```
131 If this fails, manually install missing packages as described in README.
132
133---
134
135## Configuration Issues
136
137### 5. Environment Variables Not Set
138
139**Background:** Some modules may require keys, tokens, or config settings.
140
141**Symptoms:**
142- Error: `KeyError` or warnings about missing configuration
143
144**Possible Causes:**
145- Required environment variables not set
146
147**Solutions:**
1481. **Check for `.env.example` or similar files.**
1492. **Create a `.env` file and fill in required values.**
1503. **Reload your terminal or IDE after setting environment variables.**
151
152---
153
154## Running Notebooks
155
156### 6. Notebook Will Not Open or Run
157
158**Background:** Jupyter notebooks need proper setup.
159
160**Symptoms:**
161- Notebook fails to launch
162- Browser not opening automatically
163
164**Possible Causes:**
165- Jupyter not installed
166- Browser configuration issues
167
168**Solutions:**
1691. **Install Jupyter (see Installation Issues above).**
1702. **Open notebooks manually.**
171 - Copy the URL from terminal (e.g., `http://localhost:8888/?token=...`) and paste it into your browser.
172
173### 7. Kernel Crashing or Freezing
174
175**Background:** Notebook kernels can crash due to resource limits or code errors.
176
177**Symptoms:**
178- Kernel dies or restarts repeatedly
179- Out-of-memory errors
180
181**Possible Causes:**
182- Large datasets
183- Incompatible code or packages
184
185**Solutions:**
1861. **Restart the kernel.**
187 Use the "Restart Kernel" button in Jupyter.
1882. **Check memory usage.**
189 Close unused applications.
1903. **Run notebooks on cloud platforms.**
191 Use [Google Colab](https://colab.research.google.com/) or [Azure Notebooks](https://notebooks.azure.com/).
192
193---
194
195## Performance Problems
196
197### 8. Notebooks Running Slowly
198
199**Background:** Some AI tasks require significant memory and CPU.
200
201**Symptoms:**
202- Slow execution
203- Laptop fan running loudly
204
205**Possible Causes:**
206- Large datasets or models
207- Limited system resources
208
209**Solutions:**
2101. **Use a cloud platform.**
211 - Upload notebook to Colab or Azure Notebooks.
2122. **Reduce dataset size.**
213 - Use sample data for practice.
2143. **Close unnecessary programs.**
215 - Free up system RAM.
216
217---
218
219## Textbook Website Problems
220
221### 9. Chapter Not Loading
222
223**Background:** The online textbook displays lessons and chapters.
224
225**Symptoms:**
226- A chapter (e.g., Transformers/BERT) is missing or not opening
227
228**Known Issue:**
229- [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`).
230
231**Solutions:**
2321. **Check for file renaming errors.**
233 If you’re a contributor, ensure chapter files are named `README.md`.
2342. **Report missing files.**
235 Open a GitHub issue with the chapter name and error details.
236
237---
238
239## Contributing Issues
240
241### 10. PR Not Accepted or Builds Failing
242
243**Background:** Contributions must pass tests and follow guidelines.
244
245**Symptoms:**
246- Pull request rejected
247- CI/CD pipeline errors
248
249**Possible Causes:**
250- Failing tests
251- Not following coding standards
252
253**Solutions:**
2541. **Read the contribution guidelines.**
255 - Follow the repository’s [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md).
2562. **Run tests locally before pushing.**
2573. **Check for linting rules or formatting requirements.**
258
259---
260
261## FAQ
262
263### Where can I find help for specific modules?
264- Each module usually has its own README. Start there for setup and usage tips.
265
266### How do I report a bug or request a feature?
267- [Open a GitHub Issue](https://github.com/microsoft/AI-For-Beginners/issues/new) with a clear description and steps to reproduce.
268
269### Can I ask for help if my problem isn’t listed?
270- Yes! Search existing issues first, and if you don’t find your problem, create a new issue.
271
272---
273
274## Getting Help
275
276- **Check Issues:** [GitHub Issues](https://github.com/microsoft/AI-For-Beginners/issues)
277- **Ask Questions:** Use GitHub Discussions or open an issue.
278- **Community:** See repository links for chat/forum options.
279
280---
281
282_Last Updated: 2025-09-20_
283
284---
285
286**Disclaimer**:
287This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we aim for accuracy, please note that automated translations may contain errors or inaccuracies. The original document in its native language should be regarded as the authoritative source. For critical information, professional human translation is recommended. We are not responsible for any misunderstandings or misinterpretations resulting from the use of this translation.