Troubleshooting Development Issues

Common development problems and their solutions

Build Issues

Clean Build

If you encounter unexpected build errors, try a clean build:

1. Remove Build Artifacts

   yarn

   yarn clean-slate
   

   This removes:

   • node_modules/ directory
   • app/node_modules/ directory
   • out/ build output directory
2. Reinstall Dependencies

   Dependencies are automatically reinstalled after running clean-slate.

3. Rebuild the Application

   yarn

   yarn build:dev
   

Hard Rebuild

Use the combined rebuild commands:

yarn

# Development
yarn rebuild-hard:dev

# Production
yarn rebuild-hard:prod

Hard rebuilds remove all dependencies and build artifacts. This may take several minutes.

Node.js and npm Issues

Version Compatibility

Ensure you’re using compatible versions:

node -v   # Should be >= 10
yarn -v   # Should be >= 1.9

If versions are incompatible:

macOS/Linux

# Use nvm to install the correct Node version
nvm install 20
nvm use 20

Yarn Installation

If Yarn is not installed:

npm install -g yarn

Windows-Specific Issues

node-keytar Build Failures

If keytar fails to build during npm install:

npm ERR! keytar@3.0.2 install: `node-gyp rebuild`
npm ERR! Exit status 1

Solution: Update npm to the latest version:

npm install -g npm@latest

Then retry installation:

npm install

Build Tools Missing

Windows builds require Visual Studio Build Tools:

1. Install Build Tools

   Download Visual Studio Build Tools

2. Select Components

   During installation, select:

   • Desktop development with C++
   • Windows 10 SDK
3. Retry Build

   yarn build:dev
   

Python Not Found

Node-gyp requires Python 3.9+:

1. Install Python from python.org
2. Add Python to PATH during installation
3. Verify installation:
   python --version
   

macOS-Specific Issues

Xcode Command Line Tools

If compilation fails on macOS:

xcode-select --install

Accept the license agreement:

sudo xcodebuild -license accept

macOS Version Validation

Validate your macOS version is supported:

yarn

yarn validate-macos-version

Electron Issues

Electron Version Mismatch

Validate the Electron version:

yarn

yarn validate-electron-version

Electron Download Failures

If Electron fails to download during installation:

1. Check network connection and firewall settings
2. Use a proxy if behind corporate firewall:
   export ELECTRON_MIRROR="https://npm.taobao.org/mirrors/electron/"
   yarn install
   
3. Download manually and set the cache:
   export ELECTRON_CACHE="/path/to/electron/cache"
   yarn install
   

Runtime Issues

Application Won’t Start

If the app crashes on startup:

1. Check Console Output

   Look for errors in the terminal where you ran yarn start

2. Clear Application Data

   macOS

   rm -rf ~/Library/Application\ Support/GitHub\ Desktop/
   
3. Check Logs

   View application logs for detailed error messages:

   macOS

   ls ~/Library/Application\ Support/GitHub\ Desktop/logs/*.log
   

Hot Reload Not Working

If changes aren’t reflected after reloading (Ctrl/Cmd+Alt+R):

1. Check webpack compilation in the terminal
2. Look for compilation errors in DevTools console
3. Restart the development server:
   # Stop the current server (Ctrl+C)
   yarn start
   
4. For main process changes, rebuild:
   yarn build:dev
   yarn start
   

Memory Issues

If you encounter out-of-memory errors during build:

export NODE_OPTIONS="--max_old_space_size=8192"
yarn build:prod

The production build script already sets memory to 4GB. Increase further if needed.

Test Issues

Tests Failing Locally

If tests pass in CI but fail locally:

1. Clear test cache:

   rm -rf .cache
   yarn test
   

2. Run test setup:

   yarn test:setup
   

3. Check Node version matches CI environment

Specific Test Failures

Run a specific test to isolate issues:

yarn test:unit app/test/unit/specific-test.ts

Add --test-name-pattern to run a single test case:

yarn test:unit --test-name-pattern "test name"

Linting Issues

ESLint Cache Problems

Clear the ESLint cache:

rm -rf .eslintcache
yarn lint

Prettier Conflicts

If Prettier and ESLint have conflicting rules:

yarn

yarn eslint-check

This validates that ESLint and Prettier configurations are compatible.

Git Issues

Submodule Problems

Update submodules if you see missing dependencies:

git submodule update --init --recursive

Uncommitted Changes

If you see “working directory not clean” errors:

git status
git stash
# or commit your changes

TypeScript Issues

Type Errors

If you encounter type errors:

1. Ensure dependencies are installed:

   yarn install
   

2. Restart your TypeScript server (in VS Code: Cmd+Shift+P → “TypeScript: Restart TS Server”)

3. Check TypeScript version:

   yarn list typescript
   

4. Verify tsconfig.json hasn’t been modified

Compilation Issues

Check TypeScript compilation separately:

yarn compile:script

Network and Proxy Issues

Corporate Proxy

Configure npm to use a proxy:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

For Yarn:

yarn config set proxy http://proxy.company.com:8080
yarn config set https-proxy http://proxy.company.com:8080

Certificate Issues

If you encounter SSL certificate errors:

# Temporary workaround (not recommended for production)
export NODE_TLS_REJECT_UNAUTHORIZED=0
yarn install

Disabling certificate validation is a security risk. Only use this temporarily and restore security settings afterward.

GitHub Enterprise Authentication

If you’re using GitHub Enterprise with your development build, follow the Enterprise authentication guide.

Dependency Issues

Lockfile Conflicts

If you have merge conflicts in yarn.lock:

git checkout --theirs yarn.lock
yarn install

Outdated Dependencies

Check for outdated dependencies:

yarn outdated

Be cautious when updating dependencies, as they may introduce breaking changes.

Getting Help

If you’re still experiencing issues:

1. Search existing issues: Check GitHub Issues for similar problems
2. Check logs: Review application logs for detailed error messages
3. Ask for help: Open a new issue with:
   • Your operating system and version
   • Node.js and Yarn versions
   • Complete error message
   • Steps to reproduce

Next Steps

• Review Building instructions
• Check Testing documentation
• Verify Linting setup