Skip to main content

Troubleshooting Guide

This comprehensive troubleshooting guide covers common issues you might encounter during the setup process and their solutions.

General Troubleshooting Principles​

Before diving into specific issues:

  1. Read error messages carefully - They usually contain helpful information
  2. Check you're in the correct directory - Many commands are location-specific
  3. Restart your terminal - This resolves many environment-related issues
  4. Update your tools - Ensure you're using the latest versions
  5. Check internet connection - Many operations require stable connectivity

Tool Installation Issues​

Git Installation Problems​

Issue: "command not found: git"

Cause: Git is not installed or not in your system PATH

Solution:

# macOS
brew install git
# or download from https://git-scm.com/download/mac

# Windows
# Download from https://git-scm.com/download/windows

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install git

# Verify installation
git --version

Issue: Git commands require authentication repeatedly

Cause: Git credentials not configured properly

Solution:

# Configure Git with your information
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set up credential helper (optional)
git config --global credential.helper store

Node.js Installation Problems​

Issue: "command not found: node" or "command not found: npm"

Cause: Node.js not installed or not in PATH

Solution:

# Download and install from https://nodejs.org
# Choose the LTS version

# Verify installation
node --version
npm --version

# If installed but not in PATH (macOS/Linux):
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Issue: Node.js version too old

Cause: Your Node.js version is below v18

Solution:

# Check current version
node --version

# Install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install latest Node.js
nvm install --lts
nvm use --lts
nvm alias default node

Wrangler CLI Installation Problems​

Issue: Permission denied during Wrangler installation

Cause: Insufficient permissions for global npm installation

Solution:

# macOS/Linux
sudo npm install -g wrangler@latest

# Windows (run Command Prompt as Administrator)
npm install -g wrangler@latest

# Alternative: Use npx instead of global installation
npx wrangler --version

Issue: Wrangler installation fails

Cause: npm cache corruption or network issues

Solution:

# Clear npm cache
npm cache clean --force

# Try installing again
npm install -g wrangler@latest

# If still failing, try with different registry
npm install -g wrangler@latest --registry https://registry.npmjs.org/

Account Setup Issues​

GitHub Issues​

Issue: Can't create GitHub account

Common causes and solutions:

  • Email already in use: Use a different email or recover existing account
  • Username taken: Choose a different username
  • Email verification failed: Check spam folder and click verification link

Issue: Repository forking fails

Cause: Various GitHub-related issues

Solution:

# Ensure you're logged into GitHub
# Check if you have reached repository limits (unlikely with free accounts)
# Try forking again after a few minutes
# Contact GitHub support if persistent

Issue: Can't push to repository

Cause: Authentication or permission issues

Solution:

# Check if you're pushing to your fork (not the original)
git remote -v

# Should show your username in the URL
# If not, fix the remote:
git remote set-url origin https://github.com/YOUR-USERNAME/REPO-NAME.git

# Set up SSH keys for easier authentication
ssh-keygen -t ed25519 -C "your-email@example.com"
# Then add the public key to GitHub

Cloudflare Issues​

Issue: Wrangler login fails

Cause: Browser/firewall blocking authentication

Solution:

# Try manual login
wrangler login --browser=false

# This will give you a URL to visit manually
# Copy the provided token back to your terminal

# Alternative: Check firewall/proxy settings
# Try a different browser
# Disable VPN temporarily

Issue: "wrangler whoami" shows wrong account

Cause: Logged into wrong Cloudflare account

Solution:

# Logout and login again
wrangler logout
wrangler login

# Verify correct account
wrangler whoami

Repository Setup Issues​

Cloning Issues​

Issue: "Repository not found" when cloning

Cause: Incorrect URL or repository name

Solution:

# Double-check your GitHub username
# Ensure repository was successfully forked
# Use the correct URL format:
git clone https://github.com/YOUR-USERNAME/blazenote-frontend.git

# Check if repository exists in your GitHub account
# Go to: https://github.com/YOUR-USERNAME

Issue: Permission denied when cloning

Cause: Authentication issues

Solution:

# Use HTTPS instead of SSH if SSH isn't set up
git clone https://github.com/YOUR-USERNAME/blazenote-frontend.git

# Or set up SSH keys:
ssh-keygen -t ed25519 -C "your-email@example.com"
# Add public key to GitHub, then try SSH URL

Branch Issues​

Issue: "starter" branch doesn't exist

Cause: "Copy the main branch only" was checked during forking

Solution:

# Check available branches
git branch -a

# If only main exists, you need to re-fork
# Delete your fork from GitHub
# Fork again with "Copy the main branch only" UNCHECKED

Issue: Can't switch to starter branch

Cause: Branch doesn't exist locally

Solution:

# Fetch all branches from remote
git fetch origin

# List all branches (including remote)
git branch -a

# Switch to starter branch
git checkout starter

# If starter branch still doesn't exist, check your fork

Environment Configuration Issues​

Dependency Installation Problems​

Issue: "npm install" fails with EACCES errors

Cause: Permission issues with npm global directory

Solution:

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm

# Or configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profile

Issue: "npm install" fails with network errors

Cause: Network connectivity or proxy issues

Solution:

# Try different npm registry
npm install --registry https://registry.npmjs.org/

# Check if you're behind a corporate firewall
# Configure npm proxy if needed:
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Clear npm cache and try again
npm cache clean --force

Issue: Module not found errors after installation

Cause: Incomplete installation or cache issues

Solution:

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear npm cache
npm cache clean --force

# Check that you're in the correct directory
pwd
ls -la package.json

Development Server Issues​

Issue: Port already in use (EADDRINUSE)

Cause: Another process is using the port

Solution:

# Find process using port 5173 (frontend)
lsof -ti:5173

# Kill the process
lsof -ti:5173 | xargs kill -9

# Or use a different port
npm run dev -- --port 3000

# For backend (port 8787)
lsof -ti:8787 | xargs kill -9

Issue: Development server starts but can't connect

Cause: Firewall or network configuration

Solution:

# Check if server is actually running
curl http://localhost:5173

# Try accessing via 127.0.0.1 instead
curl http://127.0.0.1:5173

# Check firewall settings
# Temporarily disable firewall to test
# Add exception for Node.js in firewall settings

Platform-Specific Issues​

Windows-Specific Issues​

Issue: Command not recognized in Command Prompt

Cause: Using Command Prompt instead of PowerShell or Git Bash

Solution:

  • Use PowerShell or Git Bash instead of Command Prompt
  • Install Windows Terminal for better terminal experience
  • Consider installing WSL (Windows Subsystem for Linux)

Issue: Path issues on Windows

Cause: Differences in path formats

Solution:

# Use forward slashes or escape backslashes
cd ~/projects/blazenote-frontend

# Or use Windows-style paths
cd %USERPROFILE%\projects\blazenote-frontend

macOS-Specific Issues​

Issue: "developer tools not installed"

Cause: Xcode command line tools missing

Solution:

xcode-select --install

Issue: Homebrew-related issues

Cause: Homebrew not installed or configured properly

Solution:

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Fix Homebrew permissions
sudo chown -R $(whoami) /usr/local/var/homebrew

Linux-Specific Issues​

Issue: Permission denied for package installation

Cause: Need sudo privileges

Solution:

# Install packages with sudo
sudo apt update
sudo apt install git nodejs npm

# Or use snap packages
sudo snap install node --classic

Error Message Decoder​

Common Error Patterns​

"ENOENT: no such file or directory"

  • You're in the wrong directory
  • File doesn't exist
  • Typo in filename

"EACCES: permission denied"

  • Need administrator privileges
  • Use sudo on Unix/macOS
  • Run as Administrator on Windows

"EADDRINUSE: address already in use"

  • Port is already being used
  • Kill existing process or use different port

"MODULE_NOT_FOUND"

  • Dependencies not installed
  • Run npm install
  • Check package.json exists

Getting Additional Help​

Documentation Resources​

Official Documentation:

Community Support​

Stack Overflow:

  • Search for specific error messages
  • Use tags: git, node.js, cloudflare-workers, github

GitHub Issues:

  • Check project repositories for known issues
  • Search existing issues before creating new ones

Discord/Slack:

  • Join workshop Discord server (if available)
  • Ask questions in appropriate channels

Diagnostic Commands​

Run these commands to gather system information:

# System information
echo "=== System Info ==="
uname -a
echo "OS: $(uname -s)"
echo "Architecture: $(uname -m)"

# Tool versions
echo "=== Tool Versions ==="
git --version
node --version
npm --version
wrangler --version 2>/dev/null || echo "Wrangler not installed"

# Network connectivity
echo "=== Network Test ==="
ping -c 1 github.com
ping -c 1 registry.npmjs.org

# Current working directory and permissions
echo "=== Current Environment ==="
pwd
ls -la
whoami

When to Ask for Help​

Ask for help when:

  • You've tried the troubleshooting steps above
  • Error persists after following solutions
  • You encounter an error not covered in this guide
  • You're stuck for more than 15 minutes

Before asking for help, provide:

  • Your operating system and version
  • Complete error message (copy and paste)
  • Commands you ran that caused the error
  • Output of diagnostic commands above

Prevention Tips​

Avoid common issues by:

  • Reading instructions carefully before executing commands
  • Checking you're in the correct directory
  • Using the exact usernames and repository names
  • Keeping tools updated to latest versions
  • Having a stable internet connection during setup
  • Taking breaks if frustrated - fresh eyes often solve problems

Remember: Setup issues are normal and everyone encounters them. Don't get discouraged - these problems have solutions! 🛠️