🛠️ Tool Setup Troubleshooting Guide

Use this page if something is not working.
Each section is independent — jump directly to the area you are stuck.
🌌

🚀 GitHub Commit / Config Recovery

Use these commands if git commit is failing.

• ✅ Expectation: You have a GitHub username + email

git config --list # shows your GitHub username + email.

• ❌ If not personalized, run to match your credentials:

git config --global user.name "jm1021"        # change to your GitHub ID
git config --global user.email "jm1021@gmail.com"  # change to your Email

🛰️ Directory + Clone Recovery

• ✅ Expectation: You can cd into your personal directory, and an ls shows your repo folder (ex: student).

cd ~/jm1021 # change jm1021 to your user directory name

• ❌ If cd fails, run:

mkdir ~/jm1021
cd ~/jm1021

ls # should show "student"

• ❌ If missing, run:

git clone https://github.com/jm1021/student.git # change to personal location of repo

🌠 Virtual Environment Recovery

• ✅ Expectation: Your terminal prompt shows (venv) prefix.

source venv/bin/activate

• ❌ If it fails

./scripts/venv.sh
source venv/bin/activate

• ✅ Satisfying the pre-requisites
• In project directory of your repo pwd
• Sourcing virtual environment source venv/bin/activate
• Ensure your terminal prompt shows the active virtual environment (venv).

You are now ready to load VSCode and build a proper memory to open your project.

code .

• ✅ Verify VSCode launch
• Terminal and presence of (venv) prompt
• Open your Jokes IPYNB notebook and select the Python kernel with the (venv) prefix.
• ❌ If you fail verification

You may have opened your repo project without activating the proper (venv) environment.
Check the Recent listings. If there are entries that look incorrect or outdated (bad memories), remove them all.

• Shift-Cmd-P (Mac) or Shift-Ctl-P (Windows, KASM)
• type: Clear Recently Open -- select and confirm
• close VSCode
• Repeat VSCode Launch and Memories

🪐 Version Checks

• ✅ Expectation: Run the bash script below
• Output is expected for each ### Command
• Version may be slightly different, but ask if you are not sure
• Java kernels are required for CSA only
• ❌ If it fails

Best course of action is to run OS specific activate scripts from pages project directory

./scripts/activate_ubuntu.sh # windows ubuntu
./scripts/activate_macos.sh # macos
./scripts/activate.sh # help setup git config options

# Define an array of commands
commands=("python --version" "pip --version" "ruby -v" "bundle -v" "gem -v" "jupyter --version" "jupyter kernelspec list" "git config --global user.name" "git config --global user.email")

for cmd in "${commands[@]}"; do
    echo "### Command: $cmd"
    bash -c "$cmd"
done

🌌 404 Error on GitHub Pages

• ✅ Expectation: Your GitHub Pages site loads at the expected URL without a 404 error.
• ❌ If you see a 404 error when visiting your live site:

https://your-username.github.io/your-repo/

• Check that your repository is set to public and GitHub Pages is enabled in the repo settings.
• Make sure your site is built from the correct branch (usually main or gh-pages).
• For project sites, ensure your URLs include the repo name (e.g., /your-repo/).
• Wait a few minutes after pushing changes—GitHub Pages can take time to update.
• Check for a valid index.html or index.md in the root or docs/ folder.
• If using custom domains, verify DNS and CNAME settings.
• Try a hard refresh or clear your browser cache if the error persists.

🛸 Makefile Troubleshooting

• ✅ Expectation: Running make should build or run your project as intended.
• ❌ If you get errors like "No rule to make target" or unexpected failures:

make
make clean
cat Makefile

• Check for typos or incorrect indentation (use tabs, not spaces, for commands in Makefiles).
• Ensure the target you are running exists in your Makefile.
• If you see permission errors, try: chmod +x scripts/your_script.sh
• Run make clean to remove old build files and try again.
• If you edited the Makefile, make sure to save it before running make.
• For debugging, add @echo statements or run make -n to see what would be executed.

🌟 Hopefully this helped!

If you made it this far, your troubleshooting journey is complete.
May your code be bug-free and your pages always load! 🚀✨