Troubleshooting

Common problems and how to fix them.

Setup Issues

“command not found: mise”

Cause: mise isn’t in your PATH, or Terminal wasn’t restarted.

Fix: Close Terminal completely and reopen it. On macOS, use Cmd + Q to fully quit.

“command not found: bundle” or “command not found: jekyll”

Cause: Ruby isn’t installed or mise isn’t activated.

Fix: Check which Ruby is being used:

which ruby

If it shows /usr/bin/ruby (system Ruby), mise isn’t working. Try:

mise trust
mise install

“bundle install” fails with permission errors

Cause: You’re using system Ruby instead of mise Ruby.

Fix: Check which ruby. It should show a path containing .local/share/mise/. If not, ensure mise is activated in your shell config.

“Your Ruby version is X, but your Gemfile specified Y”

Cause: The project expects a different Ruby version than what you have.

Fix:

mise install

This installs the correct Ruby version defined in mise.toml.

Build Issues

Jekyll build fails with “Liquid syntax error”

Cause: There’s a typo in a template file.

Fix: The error message will tell you which file and line number. Check for:

• Unclosed {% %} or {{ }} tags
• Missing endif or endfor
• Typos in variable names

Changes not showing up

Cause: Browser cache or Jekyll didn’t rebuild.

Fix:

1. Hard refresh: Cmd + Shift + R (macOS) or Ctrl + Shift + R (Windows/Linux)
2. Stop Jekyll (Ctrl + C) and restart: bundle exec jekyll serve

Images not loading

Cause: Wrong file path or filename.

Fix: Check that:

• The image file exists in assets/images/
• The filename in your YAML matches exactly (case-sensitive)
• You’re using the correct path format: /assets/images/speakers/jane-doe.jpg

YAML Issues

Indentation errors

Cause: YAML requires spaces, not tabs. Wrong indentation breaks the file.

Fix: Configure your editor to use spaces (2 spaces per indent). Look for mixed tabs/spaces:

# Wrong (tabs or inconsistent)
event:
	name: "My Event"    # Tab character

# Correct (2 spaces)
event:
  name: "My Event"

Strings with special characters

Cause: Values containing colons, quotes, or special characters need to be quoted.

Fix: Wrap the value in quotes:

# Wrong
description: Welcome: An Introduction

# Correct
description: "Welcome: An Introduction"

YAML changes not appearing

Cause: Jekyll doesn’t always detect YAML file changes.

Fix: Stop the server (Ctrl + C) and restart:

bundle exec jekyll serve

Field Name Issues

People not displaying

Cause: Using wrong field names in speakers/en.yml.

Fix: Check these common mistakes:

Event details not showing

Cause: Using wrong field names in site.yml.

Fix: Check these common mistakes:

Facilitators not appearing on schedule

Cause: Using names instead of IDs in schedule.yml.

Fix: Use facilitator IDs that match entries in speakers/en.yml:

# Wrong
facilitators:
  - "Dr. Jane Doe"

# Correct
facilitators:
  - jane-doe

Language Issues

Language switcher not working

Cause: Wrong front matter format or missing language in strings.

Fix: Check the alternate field uses an object, not separate fields:

# Wrong
alternate_lang: en
alternate_url: /

# Correct
alternate:
  en: /
  hi: /hi/

Also ensure your language is listed in _data/strings/[lang].yml under language_switcher.

Deployment Issues

“gh-pages branch not found” when deploying

Cause: First-time deployment hasn’t created the branch yet.

Fix: Run the deploy command:

bundle exec rake deploy

This creates the gh-pages branch automatically.

Site shows 404 after deployment

Cause: GitHub Pages isn’t configured correctly.

Fix:

1. Go to your repo on GitHub
2. Settings → Pages
3. Under “Source”, select “Deploy from a branch”
4. Select gh-pages branch and / (root)
5. Save and wait a few minutes

Site shows old content after deployment

Cause: GitHub Pages cache or CDN delay.

Fix: Wait 5-10 minutes. GitHub Pages can take time to update. You can also:

1. Check the deployment status in GitHub → Actions tab
2. Hard refresh your browser

Still stuck?

1. Check existing GitHub Issues
2. Open a new issue with:
   • What you were trying to do
   • The exact error message
   • Your operating system
   • Output of mise doctor and ruby --version