Introduction

symbol(s) not found for architecture i386 is a linker error. It means the compiler produced references to functions, methods, or variables, but the linker could not find matching definitions for the i386 target you are building. In practice, this usually means a missing implementation, a missing library, or a library that was built for a different architecture than the one your current target expects.

What the Error Means

The compiler and the linker do different jobs.

• the compiler turns source files into object files
• the linker combines object files and libraries into the final binary

If the linker sees a reference such as myFunction() but cannot find a compiled definition for the active architecture, it emits a symbol-not-found error.

A tiny example:

1// main.cpp
2void greet();
3
4int main() {
5    greet();
6}

If no object file or library provides greet, the build compiles but fails when linking.

Why i386 Specifically Appears

i386 refers to a 32-bit Intel target. In Apple development, this error often showed up in older simulator configurations, because the simulator target expected an i386 slice while a linked library had only device or only 64-bit slices.

That means the problem is not only "missing symbol" in the abstract. It can also mean:

• the symbol exists, but not for i386
• your app is building for i386 but one dependency is only arm64 or x86_64
• a legacy target is still enabled when the dependency no longer supports it

Common Causes

The most common causes are:

• a function is declared but never defined
• a .m, .mm, .cpp, or .c file was not added to the target
• a required library is not linked at all
• the library is linked, but it lacks an i386 architecture slice
• C and C++ or Objective-C and C++ name mangling rules do not match the declaration

A very common Apple-platform case is linking a static library compiled for device builds into a simulator build.

Check Which Architectures the Library Contains

If the failure involves a library, inspect its architecture slices.

lipo -info libSomething.a

For a framework binary:

lipo -info MyFramework.framework/MyFramework

If i386 is missing but your target still builds for i386, the mismatch explains the error.

Check That the Implementation Is Really in the Target

Sometimes the symbol is missing because the file containing the implementation is not part of the target.

In Xcode, verify:

• the source file exists in the project
• target membership is enabled for the right target
• the library is listed in link settings

A simple declaration-definition mismatch example in C++:

1// util.h
2void greet(int count);
3
4// util.cpp
5#include <iostream>
6void greet(int count) {
7    std::cout << count << '\n';
8}

If main.cpp calls greet() with a different signature than what is defined, the linker can still fail even though a similarly named function exists.

Apple Build Settings Often Matter

On Apple platforms, legacy architecture settings can be the real cause. If a target still includes i386 but your dependencies do not, stop building that architecture rather than trying to force incompatible binaries together.

That is often the correct fix in old simulator projects:

• remove obsolete architectures from build settings
• update dependencies to modern binaries
• rebuild all libraries consistently for the same target set

Common Pitfalls

A common mistake is focusing only on the symbol name and ignoring the architecture suffix in the error. The symbol may exist for one architecture and still be missing for i386.

Another mistake is declaring a function in a header and assuming that is enough. The linker needs the compiled definition too.

People also often forget target membership in Xcode, especially after adding new files manually.

Finally, if the problem is a third-party library, do not patch around it blindly. Check whether the library actually contains the architecture slice your build requires.

Summary

• 'symbols not found for architecture i386 is a linker error, not a parser or compiler syntax error'
• The linker either cannot find the symbol at all or cannot find it for the i386 architecture
• Common causes are missing implementations, missing target membership, missing libraries, or architecture mismatches
• Use tools such as lipo -info to inspect library architecture support
• In Apple builds, legacy i386 targets often conflict with modern dependencies
• Fix the real source of the mismatch instead of treating the error as a generic missing-file problem