Fix DSO Missing From Command Line Error
This linker error means the final link command does not explicitly include a shared library needed to resolve a symbol, includes it in the wrong order, or is mixing incompatible library installations. The fix is to inspect the exact link command, identify which library exports the missing symbol, then add that library as a direct dependency of the target being linked. Version-conflict warnings in the same output are especially important: they often mean your headers, linker search paths, and runtime libraries do not come from one consistent installation.
Use the error text to narrow down the cause before changing flags.
| Symptom in the Build Log | Likely Cause | Fix |
|---|---|---|
undefined reference to symbol 'name' followed by libfoo.so: error adding symbols |
The target uses a symbol from libfoo.so, but libfoo is absent from the final link command |
Add the provider library to that target’s declared link dependencies |
The needed -lfoo flag appears before the object files or dependent library |
Linker processes inputs left to right; the library can be discarded before it is needed | Put object files first, then consumer libraries, then provider libraries |
Warnings say one .so may conflict with another version |
Multiple installations of the same library family are being selected | Use headers and libraries from the same prefix; remove conflicting -I and -L paths |
| It works on one machine but fails in a container or CI | A system-installed dependency was being picked up implicitly | Declare the dependency in CMake, the Makefile, or the package configuration |
| The error occurs after enabling shared-library builds | A dependency was previously pulled in indirectly and is no longer available at the final link stage | Add the missing library directly to the executable or shared-library target |
What the DSO Missing From Command Line Error Means
DSO stands for dynamic shared object, which is the ELF shared-library format used on Linux systems. A file such as libavcodec.so, libssl.so, or libiomp5.so is a DSO.
A typical error looks like this:
undefined reference to symbol 'av_packet_unref@@LIBAVCODEC_57'
/usr/local/lib/libavcodec.so.57: error adding symbols: DSO missing from command line
The first line identifies the unresolved symbol. The second line identifies a shared library that contains, or is expected to provide, that symbol.
The important detail is that the linker is processing the final command line, not merely checking whether some other shared library depends on the needed library. Modern linkers generally require the final target to state its direct dependencies clearly.
The library named in the error is a clue to the missing dependency, but the real repair belongs in the build target that directly uses the symbol.
For example:
- An object file in your application calls a function from
libfoo.so. - Your application links
libbar.so. libbar.soitself depends onlibfoo.so.- The final link may still fail if your application directly calls
libfoosymbols but does not listlibfooitself.
The version suffix matters too. In this symbol:
av_packet_unref@@LIBAVCODEC_57
LIBAVCODEC_57 indicates the ABI version expected by the object that was compiled. If the linker finds a different ABI generation, adding another -l flag may not be enough; you need to correct the conflicting installation paths.
How to Fix the DSO Missing From Command Line Error
Fix the error by identifying the missing symbol provider, adding it after dependent inputs, then rebuilding and testing the actual artifact.
Step 1: Show the Complete Link Command
Do not diagnose this error from only the final two lines of build output. You need the full compiler-driver command that invokes ld behind the scenes.
For a Make-based project, try:
make V=1
For a CMake build, use:
cmake --build build --verbose
For a Ninja build, use:
ninja -C build -v
Find the command that produces the failing executable or shared library. It will usually end with an output option such as -o program, -o libproject.so, or a target-specific output path.
Check four things in that command:
- The object file or library that needs the missing symbol is present.
- The library that exports the missing symbol is listed.
- The provider library appears after the object or consumer library that needs it.
- The command is not selecting an unexpected version through an earlier
-Lpath.
I reproduce one problem at a time in a clean container or virtual environment, because it removes machine-specific include and library paths from the diagnosis.
Step 2: Identify the Symbol Provider
Start with the symbol in the error, not the library name alone.
If the linker says an object file has an undefined reference, inspect that object:
nm -u path/to/object.o
For a shared library that may have unresolved dynamic symbols, use:
nm -D --undefined-only path/to/libconsumer.so
Then inspect a candidate provider library for the symbol:
readelf -Ws /path/to/libprovider.so | grep 'symbol_name'
For the FFmpeg example, you would look for av_packet_unref in the libavcodec library selected by your build. Do not assume that a library in /usr/lib is the one being used just because it is installed; the final link command’s -L options decide which library directory is searched first.
You can also inspect a library’s declared dependencies:
readelf -d /path/to/libconsumer.so | grep NEEDED
This is useful context, but it does not replace adding a direct dependency when your own target uses the symbol.
Step 3: Add the Library to the Target That Uses It
The durable fix is to update the build definition, not to manually edit a generated linker command.
A conventional compiler link command places object files first and libraries afterward:
cc main.o module.o -lconsumer -lprovider -o myprogram
If module.o or libconsumer needs symbols from libprovider, -lprovider must come later in the command.
For static archives, ordering is even more important. The linker usually processes libraries from left to right and does not go back to rescan a previous archive merely because a later input needs it.
Avoid using legacy workarounds that force the linker to copy transitive dependencies or ignore dependency mistakes. They can make one build pass while leaving the project fragile across Linux distributions, container images, and linker versions.
Step 4: Reconfigure, Rebuild, and Test the Actual Artifact
After changing dependencies:
- Remove or clean the affected target’s build output.
- Re-run the project’s configuration step if it generates link commands.
- Rebuild with verbose output.
- Confirm that the provider library now appears on the final link line after the dependent inputs.
- Run the built executable, test suite, or service startup check in the environment where it will be used.
A successful compile is not enough when multiple library prefixes exist. Confirm that the built program loads the intended shared libraries at runtime as well.
CMake, Makefile, and Nginx Fixes
Declare provider libraries on targets or in LDLIBS, and use headers and library paths from the same FFmpeg installation for Nginx.
CMake Targets
In CMake, use target_link_libraries() instead of appending raw flags to a global linker variable.
If an executable directly uses a provider library, declare that dependency on the executable:
target_link_libraries(my_target PRIVATE Provider::provider)
If a library target uses the provider and downstream consumers need that relationship propagated, model it on the library target:
target_link_libraries(consumer PUBLIC Provider::provider)
target_link_libraries(app PRIVATE consumer)
Use PRIVATE, PUBLIC, and INTERFACE according to who needs the dependency:
PRIVATE: only the target itself needs it.PUBLIC: the target needs it and consumers may need the usage requirement too.INTERFACE: consumers need it, while the target itself does not link it.
After a CMake build reports this error, inspect the generated link command for the failing target. For an Audacity target in a build tree, the file can be:
build/src/CMakeFiles/Audacity.dir/link.txt
In general, inspect the active build directory’s CMakeFiles/<target>.dir/link.txt file. If the provider library is absent, fix the target declaration and regenerate the build system rather than editing link.txt; CMake recreates that file.
Then rebuild the target with verbose output and verify the corrected library order in the regenerated link command.
Traditional Makefiles
For a hand-written Makefile, keep search paths and libraries separate:
LDFLAGS += -L/path/to/provider/lib
LDLIBS += -lprovider
myprogram: main.o module.o
$(CC) $^ $(LDFLAGS) $(LDLIBS) -o $@
LDFLAGS tells the linker where to search. LDLIBS names the libraries to link. A -L option alone does not link anything; it only makes a directory eligible for library lookup.
If a dependency supplies a pkg-config file, ask it for both the compiler and linker flags:
pkg-config --cflags --libs library-name
Use the resulting flags in the target that needs them. Do not copy flags from a different machine without checking that they refer to the same installed version and prefix.
Finish by running a clean rebuild so an old object file or stale generated command does not hide the problem.
Nginx With an FFmpeg-Based Module
When building Nginx with an FFmpeg-dependent module, point the compiler headers and linker search path at the same FFmpeg installation. If FFmpeg is installed under /home/linhaibo/tools/ffmpeg-3.4, the configure options are:
--with-cc-opt="-I /home/linhaibo/tools/ffmpeg-3.4/include -I /etc/ImageMagick"
--with-ld-opt="-L /home/linhaibo/tools/ffmpeg-3.4/lib"
Use the include and lib directories from the particular FFmpeg installation you intend to link, not one prefix for headers and another for libraries. Put multiple include paths together in one --with-cc-opt value rather than supplying that option repeatedly.
The --with-ld-opt setting only adds an FFmpeg library directory to the linker’s search path. The final Nginx link command must still include the necessary FFmpeg libraries through the module or build configuration.
After updating the configure command, clean the build tree, run ./configure again, build Nginx, and check the verbose link line for mixed paths such as both /usr/local/lib and a separate custom FFmpeg prefix. Before deploying the resulting binary, run your normal Nginx configuration test in the intended runtime environment.
Fix Version Conflicts Before Adding More Flags
A DSO error often appears alongside warnings like these:
warning: libavformat.so.57 may conflict with libavformat.so.54
warning: libavcodec.so.57 may conflict with libavcodec.so.54
Treat those warnings as a separate problem that can cause the missing-symbol error.
This usually happens when:
- Headers came from one FFmpeg installation and
.sofiles came from another. /usr/local/libcontains manually installed libraries that override distribution packages.- A project has both package-manager and source-built copies of the same library family.
PKG_CONFIG_PATH,CMAKE_PREFIX_PATH,LIBRARY_PATH, or custom-Iand-Lflags point to different prefixes.- Old build artifacts were compiled against an earlier ABI version.
For example, code compiled against FFmpeg headers declaring symbols from libavcodec.so.57 should not be linked against an older libavcodec.so.54. The versioned symbol in the error makes that mismatch visible.
Use one consistent dependency prefix for all of the following:
- Header files used at compile time
- Shared libraries used at link time
- Shared libraries found when the built program starts
Do not rely on LD_LIBRARY_PATH as a permanent fix. It can alter runtime loading for a test, but it does not repair a missing library on the build command line or resolve an ABI mismatch baked into the binary.
Confirm the Fix and Prevent It From Returning
Once the link succeeds, verify the final artifact rather than stopping at the build log.
Use this checklist:
- The final verbose link command contains the provider library explicitly.
- The provider appears after the objects or libraries that require it.
- Header and library paths point to one compatible dependency installation.
- The build was regenerated after changing CMake, configure flags, or package settings.
- The executable or service starts in a clean environment without relying on undeclared local paths.
- CI or container builds install and declare the same dependency set as local development.
For projects that build on multiple systems, prefer imported CMake targets, package configuration files, or well-maintained dependency metadata over hard-coded absolute library paths. Those approaches carry include paths, link requirements, and sometimes transitive dependencies in a form the build system can reason about.
Frequently Asked Questions
What does DSO missing from command line mean?
It means the linker found a required dynamic shared object but the final link command did not properly list it as a dependency of the target being built. Add the library that exports the missing symbol to the target’s declared dependencies, and place it after the inputs that need it.
Why is the library named in the error not always enough to fix it?
The named library may expose a version mismatch, an indirect dependency, or a library-order problem rather than simply a missing -l flag. Check the unresolved symbol, the full link command, and the actual library file selected by the build’s -L paths.
Does adding a -L path fix the error?
No. A -L/path/to/lib option only tells the linker where it may search for libraries. You must also link the provider library itself, such as -lprovider, or declare the dependency through CMake or another build system.
Why does the error appear only after enabling a shared library build?
Shared-library builds can expose dependencies that were previously supplied indirectly by another executable, archive, or linker behavior. Declare every library your target directly uses instead of depending on a transitive library to bring it in.
Can I disable –as-needed or use a linker workaround?
You can sometimes make a build pass by changing linker behavior, but that usually hides an incomplete dependency declaration. Fix the target’s dependency list and ordering first, then rebuild verbosely and confirm that the final link command names the required provider library directly.
How do you fix a DSO missing from command line error in a Makefile?
Put the library that provides the unresolved symbol after the objects or libraries that use it in the target’s link command. The linker resolves requested symbols as it processes later libraries, so a provider placed too early may not be used. Name that provider explicitly instead of relying on a shared library’s dependency to supply it indirectly.
