Fix Linker Namespacing Issues

This page provides solutions to common linker namespacing issues when building and running Vega apps with native code. Each issue includes error messages, causes, and step-by-step resolution instructions.

Build fails with "library found in package"

Error message:

Error: System library 'libpthread.so.0' found in package. This library is on the public ABI list and should be dynamically linked, not bundled.

Cause: Your package bundles a system library that appears on the Vega OS public ABI list. Link these libraries dynamically instead of bundling them.

Solution:

1. Remove the bundled library from your package.

2. Update your build configuration to link dynamically:

   # CMakeLists.txt example
   target_link_libraries(your_app PRIVATE pthread)
   

3. Rebuild your package:

   Copy code Copied to clipboard.

   vega build
   

4. Verify the library is no longer bundled:

   Copy code Copied to clipboard.

   vega package list-libs <your-package.vpkg>
   

Runtime error: "cannot open shared object file"

Error message:

error while loading shared libraries: libcustom.so: cannot open shared object file: No such file or directory

Cause: Your app depends on a third-party library that isn't bundled in your package.

Solution:

1. Verify the library isn't on the Vega OS public ABI list.

2. Bundle the library in your package:

   # CMakeLists.txt example
   find_library(CUSTOM_LIBRARY custom)
   install(FILES ${CUSTOM_LIBRARY} DESTINATION lib)
   

3. Rebuild and reinstall your package:

   Copy code Copied to clipboard.

   vega build
   vega device install-app --packagePath <your-package.vpkg>
   

Symbol resolution fails at runtime

Error message:

undefined symbol: custom_function

Cause: Your app relies on ambient symbols instead of explicit dependencies.

Solution:

1. Identify which library provides the missing symbol:

   Copy code Copied to clipboard.

   nm -D <library.so> | grep custom_function
   

2. Add an explicit dependency using DT_NEEDED or dlopen():

   # CMakeLists.txt example
   target_link_libraries(your_app PRIVATE custom_library)
   

3. Rebuild your package:

   Copy code Copied to clipboard.

   vega build
   

Library loaded from wrong namespace

Symptom: Your app crashes or behaves unexpectedly when calling library functions, even though the library appears to load successfully.

Cause: The dynamic linker loaded a different version of the library than expected, typically because:

• You used a fully-qualified path in dlopen()
• The library name matches one on the public ABI list

Solution:

1. Use unqualified library names in dlopen() calls:

   // Correct
   dlopen("libutil.so.1", RTLD_NOW);
      
   // Incorrect: avoid fully-qualified paths
   dlopen("/pkg/lib/aarch64/libutil.so.1", RTLD_NOW);
   

2. Verify your library isn't on the public ABI list. If it is, the system version will always load.

3. Test on actual devices to confirm correct library loading:

   Copy code Copied to clipboard.

   vega device shell -d <device>
   cat /proc/<pid>/maps | grep libutil
   

ABI validation passes but runtime fails

Symptom: Your package passes build-time ABI validation, but the app fails at runtime with linker errors.

Cause: Build-time validation can't catch all runtime scenarios, particularly:

• Dynamic dlopen paths constructed at runtime
• Ambient symbol dependencies
• Conditional library loading based on runtime state

Solution:

1. Review all dlopen() calls in your code for dynamic path construction:

   // Problematic: path constructed at runtime
   char path[256];
   sprintf(path, "/pkg/lib/%s/libcustom.so", arch);
   dlopen(path, RTLD_NOW);
      
   // Better: use unqualified name
   dlopen("libcustom.so", RTLD_NOW);
   

2. Ensure you're using unqualified library names.

3. Test thoroughly on physical devices.

4. Check device logs for linker errors:

   Copy code Copied to clipboard.

   vega device shell -d <device> logcat | grep linker
   

Missing DT_NEEDED entries

Symptom: Your app builds successfully but fails at runtime with missing symbol errors.

Cause: Your build configuration doesn't properly declare library dependencies, causing the linker to skip adding DT_NEEDED entries.

Solution:

1. Check current DT_NEEDED entries:

   Copy code Copied to clipboard.

   readelf -d <your-library.so> | grep NEEDED
   

2. Add missing dependencies to your build configuration:

   # CMakeLists.txt example
   target_link_libraries(your_app PRIVATE
       pthread
       m
       custom_library
   )
   

3. Rebuild and verify DT_NEEDED entries are present:

   Copy code Copied to clipboard.

   vega build
   readelf -d build/<arch>/your-library.so | grep NEEDED
   

Conflicting library versions

Symptom: Your app works on the Vega Virtual Device but fails on physical devices, or vice versa.

Cause: Different library versions between your bundled libraries and system libraries, or between virtual and physical device environments.

Solution:

1. Verify which libraries you bundled in your package:

   Copy code Copied to clipboard.

   vega package list-libs <your-package.vpkg>
   

2. Check for libraries that you should link dynamically instead:

   • Compare your bundled libraries against the public ABI list
   • Remove any matches and link them dynamically

3. Test on both virtual and physical devices to ensure consistency.

Related topics

• Manage native libraries with linker namespacing
• Validate Your Package with Strict ABI Check
• Use VPT for Vega App Packages

---

Last updated: Jun 18, 2026