How to fix "missing symbol called" when running Rails commands

Are you getting an error about “missing symbol called” when running Rails commands such as rails s or bin/rails s or bundle exec rails s? Did this just recently start happening, maybe after upgrading macOS, or setting up a new Mac, or running bundle install for the first time after installing a new Ruby version?

From my experience helping thousands of people with Ruby and Rails issues, you are most likely on an Apple Silicon Mac, and your Rails app has “therubyracer” and/or the “mysql2” gem in your “Gemfile”, and/or there are issues with your dev setup.

If you have “therubyracer” gem, the solution is very simple in 99% of cases: remove the gem from your Gemfile and run bundle install. This gem is no longer needed in the vast majority of Rails apps. This assumes you have Node installed locally, which Ruby on Mac does for you automatically. You will also need to have Node installed on your production server. Some hosting services, such as Heroku, will install Node automatically when they detect a Rails app.

Read more in my detailed article that explains why you don’t need the rubyracer gem, and what to use instead in the rare case that you need a JS runtime other than Node.

The “dyld: missing symbol called” error can also be caused by gems that depend on an external tool/service being installed and running via Homebrew. For example, the “mysql2” gem depends on MySQL being installed and running. The most common way to install and run MySQL is via Homebrew.

If you have the latest version of the mysql2 gem in your Rails app, and you get the “missing symbol called” error when starting your Rails server or console, then here are the most likely causes of the issue:

• Your dev setup is broken due to transferring files from an Intel Mac to an Apple Silicon Mac (with Migration Assistant for example)
• You’ve been installing things with and without Rosetta, or by prefixing terminal commands with arch -x86_64 on an Apple Silicon Mac.
• You installed a version of Ruby older than 2.7 with optflags=-Wno-error=implicit-function-declaration

Installing tools with and without Rosetta (or arch -x86_64), or transferring a dev setup from an Intel Mac to an Apple Silicon Mac, or using dangerous hack like optflags=-Wno-error=implicit-function-declaration can cause all kinds of issues, such as ld: symbol(s) not found for architecture x86_64, and “missing symbol called”, and other issues that might cause you to waste hours or days trying to figure out.

The best solution in this case is to start over with a clean slate by uninstalling all dev tools and reinstalling everything again, making sure to do it the right way this time. Most people end up doing this by backing up their hard drive, reformatting it, reinstalling macOS, and setting up their dev environment again, hoping that they are doing it the right way. This can easily take up half a day or more.

Wouldn’t it be nice if there was a way to safely back up your dev setup and clean it up in 1 minute, without having to reinstall macOS?

Well, today is your lucky day because I built a tool called Ruby on Mac that can do this for you, and so much more. After cleaning everything up in 1 minute using the “reset” mode, you can run it again in “normal” mode to reinstall everything you need in 15 minutes or less. For MySQL support, you’ll need the Ultimate version.

Join 2100+ happy customers who have saved, and will continue to save hours of time and frustration.

If you’re sure you have a clean dev setup, and you’re still getting the “dlyd: missing symbol called” error, and you’re not using therubyracer or mysql2 gem, then I would use the following process of elimination to find the culprit:

Comment out the bottom half of the gems in your Gemfile, run bundle install, then run a Rails command, such as bin/rails c. You will most likely get some kind of crash, but if it doesn’t show the “missing symbol called” error, then you know the culprit is in the bottom half of gems.

Conversely, if you still get the “dyld: missing symbol called” error, that means the culprit is in the top half of gems. And then keep commenting out half of the remaining gems until you find the culprit. Then make sure it’s up to date. Outdated gems are one of the most common issues that prevent Ruby projects from running locally on a Mac, especially Apple Silicon Macs.