Development Setup Troubleshooting

Common issues when setting up the Heatwave development environment.

Yarn Version Mismatch

Symptom: Yarn version errors or wrong yarn being used

Fix:

# Remove all yarn installs managed by mise
mise uninstall yarn --all

# Let Corepack manage Yarn exclusively
corepack enable
corepack prepare yarn@4.11.0 --activate

mise Not Activating

Symptom: Ruby/Node versions not available after setup

Fix:

# Verify mise activation is in .zshrc
grep "mise activate" ~/.zshrc

# If missing, add manually
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc

# Reload shell
source ~/.zshrc

SSL Certificate Errors

Browser Shows "Connection Not Private"

  1. Regenerate certificates:

    config/ssl/setup_mkcert.sh

  2. Clear Chrome HSTS cache: Visit chrome://net-internals/#hsts and delete:

    • www.warmlyyours.me
    • crm.warmlyyours.me
    • api.warmlyyours.me
    • warmlyyours.me

  3. Re-trust on macOS:

    export CAROOT="${PWD}/config/ssl"
mkcert -install

OpenSSL 3.6.0 Compatibility

Symptom: SSL verification errors like "certificate verify failed"

Fix: Ensure Ruby 3.4.5+ is installed (already configured in .mise.toml):

mise install ruby
ruby -v  # Should show 3.4.5+

Puma Won't Start

Symptom: Server fails to start, PID file errors

Fix:

mkdir -p tmp/pids
rm -f tmp/pids/server.pid

Assets Not Updating

Fix (full rebuild):

rm -rf .webpack-cache
yarn wp:clean
yarn wp:rebuild

Fix (with dev server running):

yarn wpd:rebuild:inplace

Database Connection Errors

Symptom: Can't connect to PostgreSQL

  1. Ensure Docker is running:

    docker compose up -d
docker compose ps  # Verify pg is healthy

  2. Verify config/database.yml settings:

    • Host: localhost
    • Port: 5432
    • Username: deploy
    • Password: deploy

Gem Installation Fails

Sidekiq Pro 401

Already handled by bin/setup, but if needed:

bundle config --local gems.contribsys.com ab733565:8c242b3c

Native Extension Failures

Rebuild gems that depend on Homebrew libraries:

bundle exec gem pristine nokogiri
bundle exec gem pristine pg

After brew upgrade (OpenSSL, libpq changes)

If gems fail with library linking errors after a Homebrew update, force a full rebuild:

Option A: Interactive prompt

bin/setup
# Select option 2 when prompted

Option B: Skip prompt

CLEAN_GEMS=1 bin/setup

This removes all gems (except bundler) and reinstalls them with fresh native extensions.

Apple Silicon (M1/M2/M3/M4)

Most gems work natively on arm64. If you need both architectures:

bundle config unset force_ruby_platform
bundle lock --add-platform arm64-darwin-24 x86_64-darwin-24

Homebrew Path Issues

Ensure Homebrew is in PATH:

# Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"

# Intel Mac
export PATH="/usr/local/bin:$PATH"

The bin/setup script handles this automatically.

Still Stuck?

  1. Check doc/development/ for detailed guides
  2. Search existing docs: grep -r "keyword" doc/
  3. Ask the team

Last Updated: November 2025