Linker command failed with exit code 1

September 6th, 2018

Filed under: Xcode | 1 comment

If you have done any programming in Xcode, you have come across the following error message when building your project:

Linker command failed with exit code 1.

This error message is frustrating because it tells you nothing besides the fact the linker command failed. You want to know what the real error is so you can fix it.

Find the Real Error

The first step to fixing a link error is to find out what the real error is. To find the real error, open Xcode’s report navigator by choosing View > Navigator > Show Report Navigator.


The report navigator shows recent builds. If you have a linker error, there will be a red icon next to the build, which you can see in the screenshot. Select the build to see the build transcript, the list of steps Xcode took to build the project.


If you have a link error, the build transcript will provide the real error message. Selecting a step from the build transcript makes a little button appear next to the step (The screenshot arrow is pointing to the button). Click that button to see a more detailed build log for that step.

The two most common link errors are undefined symbol and duplicate symbol.

Undefined Symbol Error

An undefined symbol link error occurs when the linker cannot find a data structure name or a function name. The most common cause of an undefined symbol error is a missing framework or library that contains the symbol. Some things to check to fix an undefined symbol error include the following:

  • Make sure you added the library or framework to your project.
  • Make sure the library or framework you added is in the Link Binary with Libraries build phase.
  • If you’re coding in Swift, make sure you imported the library or framework in your code with the import statement.


Header Files

If you’re coding in a language that uses header files, working with header files is another big cause of undefined symbol link errors. Make sure you include the header properly. A common error in C or C++ code is to include a header file that’s not a system header with angle brackets.

#include <MyHeader.h>

Xcode won’t be able to find MyHeader.h in this case because the header is not a system header. Use quotes to include the header file.

#include "MyHeader.h"

Search Paths

If none of the fixes I mentioned earlier work, you may need to add search paths for the library, framework, or header file so Xcode can find them. Xcode has a Search Paths collection of build settings, which you can access from the project editor.


Duplicate Symbol Error

A duplicate symbol error occurs when the linker finds two or more data structures or functions with the same name. People using Xcode to learn C++ can run into this error if they create a command-line tool project. The command-line tool project includes a main.cpp file that has a main function in it. If you add a new file with its own main function and forget to remove the one Xcode created for you, you get a duplicate symbol error.

When trying to fix a duplicate symbol error, the first thing to check is that you haven’t defined a symbol twice in your project. Xcode’s find navigator helps you find all occurrences of a given symbol in your project.


If you’re using external frameworks or libraries, make sure your symbol names aren’t duplicates of symbols in the framework or library. If you are using custom namespaces in your code, make sure you set up the namespaces properly.

One thought on “Linker command failed with exit code 1

  1. Thanks for these instructions with the screenshots. I’ve now learned how to properly track down the errors.
    Much appreciated.
    Keep on Creating!
    Justin of

Leave a Reply

Your email address will not be published. Required fields are marked *