Skip to main content

​
Troubleshooting

This guide covers common issues you might encounter when setting up or running Maybern locally.

​
Backend Issues

Symptoms: uv creates a virtual environment with the wrong Python version, or you see version mismatch errors.Solution:
  1. Check what Python versions are available: 
    uv python list
  2. Verify Pyenv has the correct version active: 
    pyenv which python
  3. Pin uv to use the correct Python version: 
    uv python pin "$(pyenv which python)"
  4. Remove the existing virtual environment and reinstall: 
    rm -rf .venv
uv sync
Symptoms: connection refused errors when starting the server or running migrations.Solution:
  1. Check if PostgreSQL is running: 
    brew services list | grep postgresql
  2. Start PostgreSQL if it’s not running: 
    brew services start postgresql@13
  3. Verify the database exists: 
    psql -U maybern -d maybern -c '\dt'
  4. If the database doesn’t exist, create it: 
    createdb maybern -O maybern
Symptoms: Server fails to start with errors about missing configuration.Solution:
  1. Check if your .env file exists: 
    ls -la backend/config/.env
  2. If missing, create it from the template: 
    DJANGO_SECRET_KEY=$(python3 -c 'from django.utils.crypto import get_random_string; print(get_random_string(50))') \
  POSTGRES_DB=maybern POSTGRES_USER=maybern POSTGRES_PASSWORD=maybern \
  DJANGO_DATABASE_HOST=localhost \
  envsubst < config/.env.template > config/.env
  3. Contact your onboarding partner for additional required variables (Stytch keys, AWS credentials, etc.).
Symptoms: Python import errors when starting the server.Solution:
  1. Ensure the virtual environment is activated: 
    source .venv/bin/activate
  2. Verify you’re in the backend/ directory.
  3. Reinstall dependencies: 
    uv sync

​
Celery Issues

Symptoms: Error messages related to pycurl when starting Celery.Solution:Reinstall pycurl with the correct OpenSSL configuration:
pip uninstall pycurl
brew install openssl
brew info openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl@3/include"
pip install --install-option="--with-openssl" --install-option="--openssl-dir=/usr/local/opt/openssl" pycurl
Symptoms: Code changes don’t seem to affect Celery task behavior.Solution:Celery workers don’t always shut down cleanly. Kill all Python processes and restart:
kill $(pgrep -f python)
Then restart your server and workers:
just run-server
just run-celery
Symptoms: Celery can’t connect to Redis.Solution:
  1. Check if Redis is running: 
    brew services list | grep redis
  2. Start Redis if needed: 
    brew services start redis
  3. Verify Redis is accessible: 
    redis-cli ping
    You should see PONG.
To debug a Celery task:
  1. Install telnet: 
    brew install telnet
  2. Add a breakpoint in your task: 
    from celery.contrib import rdb
rdb.set_trace()
  3. Ensure async execution is enabled: 
    CELERY_TASK_ALWAYS_EAGER = False
  4. Watch the Celery logs for the debugger port: 
    [WARNING/PoolWorker-1] Remote Debugger:6900:
    Please telnet 127.0.0.1 6900.
  5. Connect with telnet: 
    telnet localhost 6900

​
Frontend Issues

Symptoms: Errors about unsupported Node features or version incompatibility.Solution:
  1. Check your Node version: 
    node --version
  2. Switch to the project’s Node version: 
    nvm use
  3. If the version isn’t installed: 
    nvm install
Symptoms: Dependency installation errors.Solution:
  1. Clear the pnpm cache: 
    pnpm store prune
  2. Remove node_modules and reinstall: 
    rm -rf node_modules
pnpm install
  3. Ensure you’re using the correct pnpm version: 
    pnpm --version  # Should be 9.6.0
Symptoms: Browser shows certificate warnings when accessing https://app.maybern.test:3000.Solution:
  1. Reinstall the mkcert CA: 
    mkcert -install
  2. Restart your browser.
  3. If using Firefox, you may need to manually trust the certificate in browser settings.
Symptoms: TypeScript errors related to API types being out of sync.Solution:Regenerate the API clients:
pnpm run gen
This regenerates the TypeScript types from the backend OpenAPI schema.

​
General Issues

Symptoms: Server fails to start because the port is already bound.Solution:Find and kill the process using the port:
# For port 8000 (Django)
lsof -i :8000 | grep LISTEN | awk '{print $2}' | xargs kill -9

# For port 3000 (Frontend)
lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill -9
Symptoms: Pre-commit hooks fail when committing.Solution:
  1. Run the linters manually to see specific errors: 
    # Backend
cd backend
just lint check

# Frontend
cd frontend
pnpm lint
  2. Auto-fix what’s possible: 
    # Backend
just lint fix

# Frontend
pnpm lint:fix

​
Getting Help

If you’re still stuck:
  1. Check the #engineering Slack channel for similar issues
  2. Search existing GitHub issues
  3. Ask your onboarding partner
  4. Create a new GitHub issue with:
    • Error messages (full stack trace)
    • Steps to reproduce
    • Your environment (OS, versions)