# Troubleshooting

This chapter describes potential problems with using LLDB, and how to
resolve them.

## Breakpoints on target are not being hit

You connect the debugger to the target, set a breakpoint, and
continue. But the breakpoint is never hit. Why is that? What can you
do about it?

This issue typically happen when debugging code in a shared library.
When the library is loaded, the dynamic loader tells the debugger.
The debugger then looks for the library, reads the symbols and debug
information, and updates breakpoints with new locations.

If your breakpoint is not hit, it is typically due to one of these
reasons:

- The program or the shared library is stripped (there are no symbols
or debug information).

    If the binary does not have symbols or debug information, the
debugger cannot set the breakpoint.

    To build with debug information, use -g on your compile line.
- The search paths used by LLDB to find the library were not set
correctly.

    When the library is loaded on the target, the dynamic loader tells
LLDB that it loaded the library. Because there is no file system on
the device, the library is loaded as, for example, ./libfoo.so.

    If libfoo.so is not in the current directory, LLDB will not be able
to find it. You can tell LLDB where to look with the following
command:

target modules search-paths add
        Copy to clipboard

    If libfoo.so is in /local/mnt/target/libs, run the following command:

target modules search-paths add . /local/mnt/target/libs
        Copy to clipboard

    This command tells LLDB to replace the period (.) at the start of the
library name with the following string: `/local/mnt/target/libs`

    Thus, `./libfoo.so` becomes `/local/mnt/target/libs/libfoo.so`. Ensure
that you match the trailing slashes in the two arguments:

target modules search-paths add ./ /local/mnt/target/libs
        Copy to clipboard

    This command changes `./libfoo.so` to `/local/mnt/target/libslibfoo.so`,
and LLDB will not be able to find libfoo.so.
- The code was not run.

    If the breakpoint address is not run, the breakpoint will not be hit.
- The code was run before the breakpoint was set.

    The breakpoint address must be run after the breakpoint is set.

If you are not sure the code at a given address is going to be run,
try setting a breakpoint on main or some other function that you know will be run.

With the following command, you can turn on logging for the LLDB
dynamic loader plug-in to see if the loader and debugger are
communicating correctly:

log enable lldb dyld
    Copy to clipboard

This command tells you what LLDB sees each time the loader
communicates with LLDB, and what the link map is as LLDB walks it.

## File and line breakpoints are not being hit

If your file and line breakpoints are not being hit, first verify
that your source files were compiled with debug information.
Typically, this means passing -g to the compiler when compiling your
source file.

When setting breakpoints in implementation source files (.c, .cpp,
.cxx, .m, .mm, and so on), by default, LLDB searches only for compile
units whose file names match. If your code does tricky things such as
using #include to include source files, breakpoints in bar.c file are
inlined into the compile unit for the foo.c file:

% cat foo.c #include "bar.c" #include "baz.c"
    Copy to clipboard

If your code does this, or if your build system combines multiple
files such that breakpoints from one implementation file are compiled
into another implementation file, you must instruct LLDB to always
search for inlined breakpoint locations by adding the following line
to your ~/.lldbinit file:

% *echo "settings set target.inline-breakpoint-strategy always"
    >> ~/.lldbinit*
    Copy to clipboard

This line directs LLDB to always look in all compile units and search
for breakpoint locations by file and line, even if the implementation
file does not match. Setting breakpoints in header files always
searches all compile units, because inline functions are commonly
defined in header files, and they often cause multiple breakpoints to
have source line information that matches many header file paths.

If you set a file and line breakpoint using a full path to the source
file, this path must match the full paths in the debug information.
If the paths do not match (possibly due to passing in a resolved
source file path that does not match an unresolved path in the debug
information), this can cause breakpoints to not be resolved. Try
setting breakpoints using the file base name only.

If you are using an IDE and move your project in your file system and
then build again, sometimes doing a clean-then-build will solve the
issue. This will fix the issue if some .o files did not get rebuilt
after the move, because the .o files in the build folder might still
contain stale debug information with the old source locations.

LLDB supports debugging multiple ELF files, but only as separate
targets. It supports debugging a single file that is postprocessed to
contain multiple ELF files (a stitched ELF file) if the symbol tables
are combined into one table. If a postprocessed file contains more
than one symbol table, LLDB does not supported debugging this file.
The ELF standard states:

“SHT\_SYMTAB and SHT\_DYNSYM. These sections hold a symbol table.
Currently, an object file may have only one section of each type,
…” ([https://refspecs.linuxfoundation.org/elf/gabi41.pdf](https://refspecs.linuxfoundation.org/elf/gabi41.pdf))

You cannot load a stitched file without a symbol table and try to use
more than one ELF file as multiple symbol tables. You also cannot
load a file and try to use a second file as an additional symbol
table. Only one symbol table per executable is allowed, except for
shared libraries loaded by the loader in the standard way.

## Check for debug symbols

To determine if a module contains debug information, check whether
that module has any compile units (source files). For example:

(lldb) file /tmp/a.out
    (lldb) image list
    [ 0] 71E5A649-8FEF-3887-9CED-D3EF8FC2FD6E 0x0000000100000000
    /tmp/a.out
    /tmp/a.out.dSYM/Contents/Resources/DWARF/a.out
    [ 1] 6900F2BA-DB48-3B78-B668-58FC0CF6BCB8 0x00007fff5fc00000
    /usr/lib/dyld
    ...
    (lldb) script lldb.target.module['/tmp/a.out'].GetNumCompileUnits()
    1
    (lldb) script lldb.target.module['/usr/lib/dyld'].GetNumCompileUnits() 0
    Copy to clipboard

In this example, the /tmp/a.out file includes a compile unit, while
the /usr/lib/dyld file does not.

Last Published: Oct 06, 2026

[Previous Topic
Debug with the booter image](https://docs.qualcomm.com/bundle/publicresource/80-N2040-31/topics/debug-with-the-booter-image.md) [Next Topic
Architecture](https://docs.qualcomm.com/bundle/publicresource/80-N2040-31/topics/architecture.md)