Skip to main content

​
Build Issues

​
Clean Build

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

Remove Build Artifacts

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 build:dev

​
Hard Rebuild

Use the combined rebuild commands: 
# 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: 
# 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! [email protected] 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 validate-macos-version

​
Electron Issues

​
Electron Version Mismatch

Validate the Electron version: 
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

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

Check Logs

View application logs for detailed error messages:
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 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

Build docs developers (and LLMs) love

Get started for freeTalk to us