| LUFA Library 140302 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Troubleshooting Information

LUFA uses a lot of advanced features of the AVR-GCC compiler, linker, and surrounding binaries. This can sometimes lead to problems compiling applications if one of these features is buggy in the version of the tools used in a build environment. Missing utilities and incorrectly set makefile configuration options can also result in different errors being produced when compilation or other operations are attempted. The table below lists a set of commonly encountered errors and their resolutions.

Problem | Resolution
--- | ---
Error "`relocation truncated to fit: R_AVR_13_PCREL against symbol {X}`" shown when compiling. | Try compiling with the setting `LINKER_RELAXATIONS=N` in your LUFA Build System 2.0 makefile, or remove the line `-Wl,–relax` from other makefiles. Alternatively, make sure you have the latest version of the Atmel Toolchain installed for your system.
Error "`error: ld terminated with signal 11 [Segmentation fault]`" shown when compiling. | Try compiling with the setting `DEBUG_LEVEL=2` in your LUFA Build System 2.0 makefile, or make sure you are using `binutils` version 2.22 or later.
Error "`EMERGENCY ABORT: INFINITE RECURSION DETECTED`" shown when compiling. | Make sure you are using an up to date version of GNU Make when compiling. This error is a safety system added to the mid-level makefiles, to prevent an issue with GNU make or other variants of Make causing an infinitely recursive build.
Error "`Unsupported architecture "{X}"`" shown when compiling. | Ensure your makefile's `ARCH` setting is set to one of the architecture names (case-sensitive) supported by the version of LUFA you are compiling against.
Error "`Makefile {X} value not set`" shown when compiling. | The specified Makefile value was not configured in your project's makefile or on the command line, and the nominated setting is required by one or more LUFA build system modules. Define the value in your project makefile and try again.
Error "`Makefile {X} option cannot be blank`" shown when compiling. | The specified Makefile value was configured in your project's makefile or on the command line, but was set to an empty value. For the nominated configuration option, an empty value is not allowed. Define the nominated setting to a correct non-blank value and try again.
Error "`Makefile {X} option must be Y or N`" shown when compiling. | The specified Makefile value was configured in your project's makefile or on the command line, but was set to a value other than a Y (for "Yes") or "N" (for "No"). This configuration option is required to be one of the aforementioned boolean values, and other values are invalid. Set this option to either Y or N and try again.
Error "`Unknown input source file formats: {X}`" shown when compiling. | The nominated source files, specified in your project's makefile in the `SRC` configuration option, has an extension that the LUFA build system does not recognise. The file extensions are case sensitive, and must be one of the supported formats (`*.c`, `*.cpp` or `*.S`).
Error "`Cannot build with OBJDIR parameter set - one or more object file name is not unique`" shown when compiling. | When a project is built with a non-empty `OBJDIR` object directory name set, all input source files must have unique names, excluding extension and path. This means that input files that are named identically and differ only by their path or extension are invalid when this mode is used.
Error "`Source file does not exist: {X}`" shown when compiling. | The nominated input source file, specified in the user project's `SRC` parameter, could not be found. Ensure the source file exists and the absolute or relative path given in the user project makefile is correct and try again.
Error "`Doxygen configuration file {X} does not exist`" shown when upgrading a Doxygen configuration file. | The nominated Doxygen configuration file, specified in the user project's `DOXYGEN_CONF` parameter, could not be found. Ensure the configuration file exists and the absolute or relative path given in the user project makefile is correct and try again, or run the appropriate makefile target to generate a new configuration file.
Error "`avr-gcc: error: unrecognized option '{X}'`" shown when compiling. | An unrecognised option was supplied to the compiler, usually in the `C_FLAGS`, `CPP_FLAGS`, `ASM_FLAGS` or `CC_FLAGS` configuration options. The nominated compiler switch may be invalid, or unsupported by the version of AVR-GCC on the host system. Remove the unrecognised flag if invalid, or upgrade to the latest AVR-GCC. If the option is a valid linker option, use the prefix "-Wl," to ensure it is passed to the linker correctly.
Error "`makefile:{X}: {Y}.mk: No such file or directory`" shown when make is invoked. | The path to the nominated makefile module was incorrect. This usually indicates that the makefile `LUFA_PATH` option is not set to a valid relative or absolute path to the LUFA library core.
Error "`fatal error: LUFAConfig.h: No such file or directory`" shown when compiling. | The `USE_LUFA_CONFIG_HEADER` compile time option was set in the user project makefile, but the user supplied `LUFAConfig.h` header could not be found. Ensure that the directory that contains this configuration file is correctly passed to the compiler via the -I switch in the makefile `CC_FLAGS` parameter.
Error "`ld.exe: section .apitable_trampolines loaded at {X} overlaps section .text`" shown when compiling a bootloader. | The bootloader is compiling too large for the given `FLASH_SIZE_KB` and `BOOT_SECTION_SIZE_KB` parameters set in the bootloader makefile. This usually indicates that these values are incorrect for the specified device the bootloader is targeting. If these values are correct, a newer version of the compiler may need to be used to ensure that the bootloader is built within the section size constraints of the target device.
Error "`unknown MCU '{X}' specified`" shown when compiling. | The specified microcontroller device model name set in the user application's makefile as the `MCU` parameter is incorrect, or unsupported by the version of the compiler being used. Make sure the model name is correct, or upgrade to the latest Atmel Toolchain to obtain newer device support.
Error "`undefined reference to `{X}'`" shown when compiling. | This is usually caused by a missing source file in the user application's `SRC` configuration parameter. If the indicated symbol is one from the LUFA library, you may be missing a LUFA source makefile module (see The SOURCES build module).

For troubleshooting other errors you encounter, please see Assistance With LUFA.