How to solve the Mac OS/X “stub file and library file out of sync” problem

UPDATE: Multiple people have reported in the comments that the recent update to MacOS 10.13.6 has produced the same issue for them, and that the procedure below has not addressed it this time. However, this OS update didn’t leave my system with any ill effects. If you’ve experienced this and have found a solution, would you be willing to leave a comment at the bottom summarizing the solution? Thanks.

I ran across this annoying little problem while compiling Go code on my Mac. I just spent the last hour or so scouring Google results trying to find the answer, and eventually pieced together a solution. (I’ve been spending a lot of my time recently studying GoLang, which will undoubtedly make additional future appearances on this blog.)

The issue is lines of the form “warning: text-based stub file TBD-file-path and library file library-file-path are out of sync. Falling back to library file for linking.” Sometimes a lot of such lines.

While these messages are warnings and can safely be ignored, they’re awful annoying. And they clutter up the build output, possibly obscuring useful warnings that we really need to pay attention to.

Unfortunately, figuring out why the files were out of sync and how to re-sync them was not a trivial task. (It should have been. Apple? Are you listening?) This seems to be the result of a bug in Apple’s developer-tools installation. I spent the last hour piecing together a simple-but-nonobvious solution, and am recording it here for posterity (and in case anyone else would like to try it out).

You can skip to the end for the solution. The next section tells the story of what’s going on and the probable cause of the bug.

I first noticed the warnings when I ran go get. (I haven’t been doing too much with compiled code lately, and I’m not sure how long this issue has been around.) In the command output, I saw lines like these:

ld: warning: text-based stub file /System/Library/Frameworks//CoreFoundation.framework/CoreFoundation.tbd and library file /System/Library/Frameworks//CoreFoundation.framework/CoreFoundation are out of sync. Falling back to library file for linking.
ld: warning: text-based stub file /System/Library/Frameworks//Security.framework/Security.tbd and library file /System/Library/Frameworks//Security.framework/Security are out of sync. Falling back to library file for linking.

These warnings are caused by the linker, which is looking at the TBD files to get metadata about the corresponding libraries, but it’s determining that the TBD files are out of date and need to be rebuilt.

Apple switched from dylib to TBD files in 2015. At some point thereafter, I updated my OS and updated Xcode, but the TBD files apparently never got updated. These are normally updated along with the command-line tools, but either there was no command-line tools update or else there was a broken update. And since then, I gather, linking against framework libraries has produced these warnings. All of the instances I pulled up via Google Search are fairly recent (back to early 2018), so perhaps this is a new phenomenon.

Usually this warning appears because you need to update Xcode and the command-line tools.

But I had already updated Xcode, and there was no command-line tools update. Running xcode-select --install produced the message: “error: command line tools are already installed, use ‘Software Update’ to install updates”—which frankly was rather unhelpful advice. I think by “Software Update,” they mean the updater in the app store or the softwareupdate command-line tool. Neither knew anything about the Xcode command-line tools.

The solution was to forcibly remove the command-line tools and reinstall them.

$ sudo mv /Library/Developer/CommandLineTools /Library/Developer/CommandLineTools.old
$ xcode-select --install
$ sudo rm -rf /Library/Developer/CommandLineTools.old

The actual reinstall process took several minutes to complete.

Please be especially careful with that last line! Alliances between sudo and rm ‑rf can end in great violence.

And keep regular system backups. Just do it. Please.

After this, my Go apps built cleanly without warnings. (Yay!)

This entry was posted in Uncategorized and tagged , . Bookmark the permalink.

26 Responses to "How to solve the Mac OS/X “stub file and library file out of sync” problem"

Leave a reply