Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
603 lines (430 loc) · 13.2 KB

TROUBLESHOOTING.md

File metadata and controls

603 lines (430 loc) · 13.2 KB

Troubleshooting Guide

Dis guide go help you solve common wahala wey fit happen wen you dey work wit di Machine Learning for Beginners curriculum. If you no see solution here, abeg check our Discord Discussions or open an issue.

Table of Contents

Installation Wahala

Python Installation

Wahala: python: command not found

Solution:

  1. Install Python 3.8 or higher from python.org
  2. Check say Python don install: python --version or python3 --version
  3. For macOS/Linux, you fit need use python3 instead of python

Wahala: Multiple Python versions dey cause wahala

Solution:

# Use virtual environments to isolate projects
python -m venv ml-env

# Activate virtual environment
# On Windows:
ml-env\Scripts\activate
# On macOS/Linux:
source ml-env/bin/activate

Jupyter Installation

Wahala: jupyter: command not found

Solution:

# Install Jupyter
pip install jupyter

# Or with pip3
pip3 install jupyter

# Verify installation
jupyter --version

Wahala: Jupyter no wan open for browser

Solution:

# Try specifying the browser
jupyter notebook --browser=chrome

# Or copy the URL with token from terminal and paste in browser manually
# Look for: http://localhost:8888/?token=...

R Installation

Wahala: R packages no wan install

Solution:

# Ensure you have the latest R version
# Install packages with dependencies
install.packages(c("tidyverse", "tidymodels", "caret"), dependencies = TRUE)

# If compilation fails, try installing binary versions
install.packages("package-name", type = "binary")

Wahala: IRkernel no dey available for Jupyter

Solution:

# In R console
install.packages('IRkernel')
IRkernel::installspec(user = TRUE)

Jupyter Notebook Wahala

Kernel Wahala

Wahala: Kernel dey die or restart anyhow

Solution:

  1. Restart di kernel: Kernel → Restart
  2. Clear output and restart: Kernel → Restart & Clear Output
  3. Check memory wahala (see Performance Wahala)
  4. Try run di cells one by one to see di code wey dey cause wahala

Wahala: Wrong Python kernel dey selected

Solution:

  1. Check di current kernel: Kernel → Change Kernel
  2. Select di correct Python version
  3. If kernel no dey, create am:
python -m ipykernel install --user --name=ml-env

Wahala: Kernel no wan start

Solution:

# Reinstall ipykernel
pip uninstall ipykernel
pip install ipykernel

# Register the kernel again
python -m ipykernel install --user

Notebook Cell Wahala

Wahala: Cells dey run but output no dey show

Solution:

  1. Check if cell still dey run (look for [*] indicator)
  2. Restart kernel and run all cells: Kernel → Restart & Run All
  3. Check browser console for JavaScript errors (F12)

Wahala: Cells no dey run - no response wen you click "Run"

Solution:

  1. Check if Jupyter server still dey run for terminal
  2. Refresh di browser page
  3. Close and reopen di notebook
  4. Restart Jupyter server

Python Package Wahala

Import Errors

Wahala: ModuleNotFoundError: No module named 'sklearn'

Solution:

pip install scikit-learn

# Common ML packages for this course
pip install scikit-learn pandas numpy matplotlib seaborn

Wahala: ImportError: cannot import name 'X' from 'sklearn'

Solution:

# Update scikit-learn to latest version
pip install --upgrade scikit-learn

# Check version
python -c "import sklearn; print(sklearn.__version__)"

Version Conflicts

Wahala: Package version dey incompatible

Solution:

# Create a new virtual environment
python -m venv fresh-env
source fresh-env/bin/activate  # or fresh-env\Scripts\activate on Windows

# Install packages fresh
pip install jupyter scikit-learn pandas numpy matplotlib seaborn

# If specific version needed
pip install scikit-learn==1.3.0

Wahala: pip install dey fail wit permission wahala

Solution:

# Install for current user only
pip install --user package-name

# Or use virtual environment (recommended)
python -m venv venv
source venv/bin/activate
pip install package-name

Data Loading Wahala

Wahala: FileNotFoundError wen you dey load CSV files

Solution:

import os
# Check current working directory
print(os.getcwd())

# Use relative paths from notebook location
df = pd.read_csv('../../data/filename.csv')

# Or use absolute paths
df = pd.read_csv('/full/path/to/data/filename.csv')

R Environment Wahala

Package Installation

Wahala: Package installation dey fail wit compilation wahala

Solution:

# Install binary version (Windows/macOS)
install.packages("package-name", type = "binary")

# Update R to latest version if packages require it
# Check R version
R.version.string

# Install system dependencies (Linux)
# For Ubuntu/Debian, in terminal:
# sudo apt-get install r-base-dev

Wahala: tidyverse no wan install

Solution:

# Install dependencies first
install.packages(c("rlang", "vctrs", "pillar"))

# Then install tidyverse
install.packages("tidyverse")

# Or install components individually
install.packages(c("dplyr", "ggplot2", "tidyr", "readr"))

RMarkdown Wahala

Wahala: RMarkdown no wan render

Solution:

# Install/update rmarkdown
install.packages("rmarkdown")

# Install pandoc if needed
install.packages("pandoc")

# For PDF output, install tinytex
install.packages("tinytex")
tinytex::install_tinytex()

Quiz Application Wahala

Build and Installation

Wahala: npm install dey fail

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

# If still fails, try with legacy peer deps
npm install --legacy-peer-deps

Wahala: Port 8080 don already dey use

Solution:

# Use different port
npm run serve -- --port 8081

# Or find and kill process using port 8080
# On Linux/macOS:
lsof -ti:8080 | xargs kill -9

# On Windows:
netstat -ano | findstr :8080
taskkill /PID <PID> /F

Build Errors

Wahala: npm run build dey fail

Solution:

# Check Node.js version (should be 14+)
node --version

# Update Node.js if needed
# Then clean install
rm -rf node_modules package-lock.json
npm install
npm run build

Wahala: Linting errors dey stop build

Solution:

# Fix auto-fixable issues
npm run lint -- --fix

# Or temporarily disable linting in build
# (not recommended for production)

Data and File Path Wahala

Path Wahala

Wahala: Data files no dey wen you dey run notebooks

Solution:

  1. Always run notebooks from di directory wey dey contain dem

    cd /path/to/lesson/folder
jupyter notebook

  2. Check di relative paths for code

    # Correct path from notebook location
df = pd.read_csv('../data/filename.csv')

# Not from your terminal location

  3. Use absolute paths if e necessary

    import os
base_path = os.path.dirname(os.path.abspath(__file__))
data_path = os.path.join(base_path, 'data', 'filename.csv')

Missing Data Files

Wahala: Dataset files no dey

Solution:

  1. Check if data suppose dey di repository - most datasets dey included
  2. Some lessons fit need make you download data - check lesson README
  3. Make sure say you don pull di latest changes: 
    git pull origin main

Common Error Messages

Memory Wahala

Error: MemoryError or kernel dey die wen e dey process data

Solution:

# Load data in chunks
for chunk in pd.read_csv('large_file.csv', chunksize=10000):
    process(chunk)

# Or read only needed columns
df = pd.read_csv('file.csv', usecols=['col1', 'col2'])

# Free memory when done
del large_dataframe
import gc
gc.collect()

Convergence Warnings

Warning: ConvergenceWarning: Maximum number of iterations reached

Solution:

from sklearn.linear_model import LogisticRegression

# Increase max iterations
model = LogisticRegression(max_iter=1000)

# Or scale your features first
from sklearn.preprocessing import StandardScaler
scaler = StandardScaler()
X_scaled = scaler.fit_transform(X)

Plotting Wahala

Wahala: Plots no dey show for Jupyter

Solution:

# Enable inline plotting
%matplotlib inline

# Import pyplot
import matplotlib.pyplot as plt

# Show plot explicitly
plt.plot(data)
plt.show()

Wahala: Seaborn plots dey look different or dey throw errors

Solution:

import warnings
warnings.filterwarnings('ignore', category=UserWarning)

# Update to compatible version
# pip install --upgrade seaborn matplotlib

Unicode/Encoding Wahala

Wahala: UnicodeDecodeError wen you dey read files

Solution:

# Specify encoding explicitly
df = pd.read_csv('file.csv', encoding='utf-8')

# Or try different encoding
df = pd.read_csv('file.csv', encoding='latin-1')

# For errors='ignore' to skip problematic characters
df = pd.read_csv('file.csv', encoding='utf-8', errors='ignore')

Performance Wahala

Slow Notebook Execution

Wahala: Notebooks dey run very slow

Solution:

  1. Restart kernel to free memory: Kernel → Restart
  2. Close notebooks wey you no dey use to free resources
  3. Use smaller data samples for testing: 
    # Work with subset during development
df_sample = df.sample(n=1000)
  4. Profile your code to find di bottlenecks: 
    %time operation()  # Time single operation
%timeit operation()  # Time with multiple runs

High Memory Usage

Wahala: System dey run out of memory

Solution:

# Check memory usage
df.info(memory_usage='deep')

# Optimize data types
df['column'] = df['column'].astype('int32')  # Instead of int64

# Drop unnecessary columns
df = df[['col1', 'col2']]  # Keep only needed columns

# Process in batches
for batch in np.array_split(df, 10):
    process(batch)

Environment and Configuration

Virtual Environment Wahala

Wahala: Virtual environment no dey activate

Solution:

# Windows
python -m venv venv
venv\Scripts\activate.bat

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

# Check if activated (should show venv name in prompt)
which python  # Should point to venv python

Wahala: Packages don install but notebook no dey see dem

Solution:

# Ensure notebook uses the correct kernel
# Install ipykernel in your venv
pip install ipykernel
python -m ipykernel install --user --name=ml-env --display-name="Python (ml-env)"

# In Jupyter: Kernel → Change Kernel → Python (ml-env)

Git Wahala

Wahala: No fit pull latest changes - merge conflicts dey

Solution:

# Stash your changes
git stash

# Pull latest
git pull origin main

# Reapply your changes
git stash pop

# If conflicts, resolve manually or:
git checkout --theirs path/to/file  # Take remote version
git checkout --ours path/to/file    # Keep your version

VS Code Integration

Wahala: Jupyter notebooks no wan open for VS Code

Solution:

  1. Install Python extension for VS Code
  2. Install Jupyter extension for VS Code
  3. Select correct Python interpreter: Ctrl+Shift+P → "Python: Select Interpreter"
  4. Restart VS Code

Additional Resources

Still Get Wahala?

If you don try di solutions wey dey above and wahala still dey:

  1. Search existing issues: GitHub Issues
  2. Check discussions for Discord: Discord Discussions
  3. Open new issue: Include:
    • Your operating system and version
    • Python/R version
    • Error message (full traceback)
    • Steps wey you take to reproduce di wahala
    • Wetin you don already try

We dey here to help! 🚀

Disclaimer:
Dis docu don dey translate wit AI translation service Co-op Translator. Even though we dey try make am accurate, abeg sabi say automatic translation fit get mistake or no correct well. Di original docu for im native language na di main correct source. For important information, e go beta make professional human translator check am. We no go fit take blame for any misunderstanding or wrong interpretation wey fit happen because you use dis translation.