Common Problems

Windows Vista / Windows 7 Hibernation Note

§ On an MBR disk, Windows Vista and Windows 7 refuse to hibernate if the system volume is not marked as active in the partition table before booting Windows. However, at least in Windows 7, if the "system" partition is changed to "active" and Disk Management -> Rescan Disks is used, hibernation will then work.

To work around this for MBR disks, you can use the special partition index in altmbr.bin and let Windows believe that the system volume is "active" in the usual partition table field. "altmbr.bin" will boot the partition index you specify in its special field, regardless of the usual active flag field in the partition table entries.

Watch the name of your kernel

§ The single most common user error is setting up a kernel configuration using one of the reserved extensions:

 none or other Linux kernel image
 .0            PXE bootstrap program (NBP) [PXELINUX only]
 .bin          "CD boot sector" [ISOLINUX only]
 .bs           Boot sector [SYSLINUX only]
 .bss          Boot sector, DOS superblock will be patched in [SYSLINUX only]
 .c32          COM32 image (32-bit COMBOOT)
 .cbt          COMBOOT image (not runnable from DOS)
 .com          COMBOOT image (runnable from DOS)
 .img          Disk image [ISOLINUX only]

Especially the ".0" and ".bin" extensions affect many cases:

.0: as part of a version number: calling your kernel "redhat-9.0"
.bin: Some tools that can be booted as a linux kernel come with this extension: memtest.bin, plpbt.bin, ...

It is unfortunate that there isn't a standard extension used for Linux kernels, and that none of the commonly-loaded data formats (except perhaps COM32) have reliable magic numbers. If you want to name your kernel images something that will avoid confusion, I suggest using the extension .zi (zImage/bzImage).

To solve the issue:

change/remove the extension
use a more specific keyword than KERNEL. In most cases you will need the LINUX keyword. For other keywords see: Config#KERNEL-LIKE_DIRECTIVES.

Example with LINUX keyword instead of KERNEL:

 LABEL with_0
 LINUX redhat-9.0
 
 LABEL with_bin
 LINUX memtest.bin

What's the real name of that file?

§ When using SYSLINUX or ISOLINUX, make sure that the real name of kernels and other files are the ones you actually specify.

DOS-8.3

§ The filename format often referred to as "DOS 8.3" is defined as a filename of 1 to 8 characters, a dot ("."), and a filename extension between 0 to 3 characters. The characters are interpreted in a case-insensitive manner and stored as uppercase. The dot may be omitted if the filename extension's length is zero characters. The character set is restrictive within an 8-bit character set and includes A-Z, 0-9, "_", and "~", among others. See also http://en.wikipedia.org/wiki/8.3_filename for more details.

SYSLINUX

§ As of version 3.70, SYSLINUX can also understand VFAT filenames, with certain restrictions. VFAT filenames allow a FAT file system to store filenames that are not restricted to the normal "DOS 8.3" format. Filenames are stored as UTF-16LE but must be translated to an 8-bit character to be usable.

SYSLINUX-3.63-

§ Prior to SYSLINUX 3.70, the "real" name was the MS-DOS name, not a VFAT long filename. To verify the real name, you can mount your disk or disk image with, for example:

 mount [-r] -t msdos /dev/fd0 /mnt/floppy

The mount option " -t msdos " will prevent "long names" from showing up.

Note, in particular, that writing the filesystem with VFAT or UMSDOS enabled will produce very weird names unless they are already entered as valid 8.3 DOS filenames.

ISOLINUX

§ For ISOLINUX, the "real" name is the ISO 9660 filename, not a RockRidge or Joliet filename. The character set is

A through Z,
0 through 9,
"_", and
"." with a (max.) limit of one "." per filename.

To verify the real name, mount your CD-ROM or iso image with, for example:

 mount -r -t iso9660 -o norock,nojoliet /dev/cdrom /mnt/cdrom

The mount options " -t iso9660 -o norock,nojoliet " will prevent "long names" from showing up.

Please note that symbolic links are a RockRidge feature! You will find that if you mount your disk with " -o norock " then symbolic links show up as short files rather than as links. Therefore, you cannot reference symbolic links; however, hard links should work as expected.

If you are using mkisofs/genisoimage to generate files, there are options which reduce the amount of filename mangling:

 mkisofs -allow-leading-dots -allow-multidot -l -relaxed-filenames -no-iso-translate ...

Without "-l", the filenames will be shortened to fit in an "8.3" format and may result in heavy alterations in order to make the name unique. With "-l", this may result in compatibility issues with DOS and make some files inaccessible (some versions of DOS might be alright with the names, but results may vary). See http://en.wikipedia.org/wiki/ISO_9660#File_and_directory_name_restrictions for more information.

Official Binaries

§ If you have tried using the binaries included in your Linux distribution or compiling by hand but encountered an error, try the official pre-compiled binaries from the official distribution package (see Download). It is always recommended to try the latest available version. If you don't wish to try the latest one, you should at least try the official binaries from the same version equivalent to the distro's package. Often times, newer versions will have already addressed the issue you are experiencing and will also be one of the first recommendations given out if you are not using the current version.

If you cannot run the official installer binaries on your system due to library differences, start by rebuilding only the installers:

 make clean
 make installer

( See also Doc/distrib , Doc/building and Building )

If you have compiled it by hand and encountered issues, there are several reasons to try the official binaries before thinking you have an issue.

Your build system: It may be incomplete or be using a version of a package (compiler, etc) that may not interpret the source as well. NASM before 2.00 can not interpret certain extensions that were added in NASM 2.00 and Syslinux will fail to build from source at this point.
Diagnosing: Everyone else will be able to obtain these exact same binaries in order to analyze and diagnose your issue. Many active users and developers always have the latest version on hand and won't even need to wait for a download. If there is a genuine issue, this aids in diagnosing it.

Modules

§ Modules, especially COM32 modules (.c32 files), should ideally come from the same package as the core binaries (isolinux.bin, ldlinux.sys, pxelinux.0; ldlinux.sys and extlinux.sys are installed by the syslinux, extlinux, syslinux.com, syslinux.exe and syslinux64.exe installer binaries) that you are using. Syslinux v4+ is strictly incompatible with older COM32 modules as the format has had a significant change (COM32 to COM32R), generating a "not a COM32R image" error. Also, COM32R modules will probably be incompatible with gPXE's native/built-in COMBOOT API.

When updating the Syslinux core binaries, it is highly advised that you also update all modules at the same time. Using tools like UNetBootIn counts as an update, as many of these tools use the installer binaries (syslinux/extlinux) in the Linux distro you are using or integrate their own. These installers will often not match the versions used in the original images (like ISO files). Modules from v3.86 are generally known to be compatible with gPXE.

ELF

§ Version 5.00 and newer require an additional module (ldlinux) be loaded before a config can be loaded/parsed, specifically ldlinux.c32 (BIOS), ldlinux.e32 (EFI32) or ldlinux.e64 (EFI64).

Modules also depend on library modules such as libcom32.c32, libutil.c32, libmenu.c32, libgpl.c32, and liblua.c32.

Multi-Arch

§ Version 6.00 and newer ship with binaries in a per-architecture directory prefix; e.g. core/pxelinux.0 is found at bios/core/pxelinux.0, efi32/core/syslinux.efi is the EFI32 core binary. For the ldlinux module, the file name extensions also specify the architecture; ldlinux.c32 (BIOS), ldlinux.e32 (EFI32) and ldlinux.e64 (EFI64).

Failed to load ldlinux

§ Downloading or installing a Syslinux package is not the same as installing Syslinux as boot loader. After installing a Syslinux package, Syslinux needs to be effectively installed as boot loader. For SYSLINUX/EXTLINUX, there are installers included in Syslinux. Some Linux distros include their own methods (such as scripts) to achieve this goal. Some Syslinux variants (such as ISOLINUX) might require copying certain files to some specific location(s). For Syslinux modules to work correctly, they need to match the same (exact) version as the Syslinux boot loader. See also Library_modules#All_Syslinux_variants_need_an_additional_ldlinux_module.

See also some of the Syslinux's current limitations regarding supported filesystems.

Menu background

§ There are several possible reasons for the (vesa)menu background to be displayed incorrectly, or at least not as the user expected.

Another related symptom could be that the (vesa)menu seems to be located in an unexpected position on the screen, or with an unexpected size. Sometimes the menu is seen, but when going from the menu to the boot prompt (e.g. by means of [Esc] or [Tab] keys), the expected command line is not seen.

Check that the MENU RESOLUTION values match the resolution actually used for the background image. If "MENU RESOLUTION 1024 768" is being used in the Syslinux configuration file, then double-check that the background image actually uses such resolution. Either match the image file so as to use the values in the MENU RESOLUTION directive, or edit the MENU RESOLUTION values so as to match those actually used in the background image.
Check that the background image uses a "standard" resolution. For instance, a background image that is not 1024x768 (or not 640x480, or...), reduces the chances of obtaining an adequate boot menu (background).
It is recommended to use 24-bit (or less) color depth for PNG or JPG background images. Images with more than 24-bit colors might be displayed differently as background image for vesamenu.
Background images in LSS16 format accept only 16 colors (4-bit).
Instead of using a background image, select a fixed background color ("#AARRGGBB", see Menu#MENU_COLOR).
On BIOS hardware, comment out the MENU BACKGROUND and MENU RESOLUTION directives for a test. Are all the menu-items seen correctly? Is the command line displayed correctly? In the Syslinux configuration file, are there any additional directives present that might influence the appearance of the boot menu?
On UEFI hardware, try using "vesamenu.c32" with "MENU RESOLUTION 1024 768". If using a background image, the image should use a matching resolution.
If vesamenu seem to fail (e.g. crash, reboot, freeze...), try commenting out the MENU BACKGROUND directive in the configuration file and test again. Also try changing the format of the background image file; for instance, from PNG to JPG.

Please report your experience.

Incorrect Syntax

§ Incorrect syntax in configuration files is another common error. If you are not getting the menu or the results you expect, double check that the syntax in your configuration file(s) is correct. There is also a way to add Web Browser Syntax Highlighting which will provide some syntax clue when viewing a configuration file in a browser.

Use of labels is recommended

§ In the following (discouraged) configuration syntax, note that the DEFAULT directive is using a kernel (instead of using a label) as parameter:

 DEFAULT mykernel
 APPEND myoptions

or

 DEFAULT mykernel myoptions

Such configuration syntax is discouraged, and under certain circumstances it could fail to load the desired options.

Instead, use a label as parameter for the DEFAULT directive:

 DEFAULT mylabel
 LABEL mylabel
 KERNEL mykernel
 APPEND myoptions

Serial

§ For the SERIAL directive to be guaranteed to work properly, it should be the first directive in the configuration file.

In some cases, using the CONSOLE and/or NOHALT directives might be suggested.

If the serial directive / console fails to respond, try using alternative values or an alternative notation (e.g decimal) of the same values.

Use a different baudrate speed.
Use a different port value.
Use a port number (0, 1, 2...) instead of an I/O port address (e.g. 0x3F8).
For the serial flowcontrol parameter, convert the (hex) value to decimal notation.

Examples:

"SERIAL 1" to "SERIAL 3"
"SERIAL 0x3F8" to "SERIAL 1"
"SERIAL 0 115200 0x003" to "SERIAL 0 115200 3"
"SERIAL 0 115200 0x803" to "SERIAL 0 115200 2051"

Missing Operating System (mbr.bin)

§ Both the Syslinux and "standard" Master Boot Records will yield the message "Missing operating system." if none of the partitions in the partition table are marked as active. You can use DOS FDISK or fdisk under Linux to set the appropriate partition as active.

If your first partition is the one that you are expecting to boot with the Syslinux boot-loader installed, then under Linux you could possibly do something like:

 $ fdisk /dev/sda
 Command (m for help): a
 Partition number (1-X): 1
 Command (m for help): w

Missing OS (gptmbr.bin)

§ As stated above, the MS-DOS mbr (mbr.bin) of Syslinux provides the "Missing Operating System" error message while the GPT mbr (gptmbr.bin) provides the "Missing OS" error message. In order to fix this problem, enable the "boot" ("active") flag on the boot partition (in many cases /dev/sda1). At time of writing, parted-2.3 does not seem to do this job like expected. Instead, use "sgdisk" to get this task done.

If your first partition is the one that you are expecting to boot with the Syslinux boot-loader installed, then under Linux, one possibility to set the "boot" flag could be:

 sgdisk /dev/sda --attributes=1:set:2

To confirm everything went fine run:

 sgdisk /dev/sda --attributes=1:show

This should output:

 1:2:1 (legacy BIOS bootable)

PXE Calls in 4.00-4.03

§ pxechain.com started as the key to what the issue was. However, there is a lot more affected. Any PXE call that loads something else and destroys PXELINUX will cause a crash. Please upgrade to the latest stable (or at least 4.04, released 2011-04-18). This also affects gpxecmd.c32 and sanboot.c32.

pxechain.com/PXELINUX-4.00+

§ pxechain.com in 4.00 - 4.03 is broken. PXELINUX 4.04 solves this issue.

pxechain.com-1

§ One workaround is to start with PXELINUX 3.86 (or less) and pxechain.com from the same package (set) to load your desired files.

pxechain.com-2

§ A second partial and heavily manual workaround (if you are going to be using another PXELINUX) is to load the new PXELINUX file first (which then loads the existing config file), then use the CONFIG directive or config.c32 module to load the new config file and cwd (current working directory). This has been tested by one project contributor and worked to load a new PXELINUX, config file and cwd from another TFTP. This procedure can be done in 2 LABELS (examples in both styles; URL style requires PXELINUX 3.70+):

 LABEL newpxe1
  PXE tftp://192.168.1.3/pxe/pxelinux.0
 LABEL newcfg1
  CONFIG tftp://192.168.1.3/pxe/pxelinux.cfg/default
  APPEND tftp://192.168.1.3/pxe/
 
 LABEL newpxe2
  PXE 192.168.1.3::pxe/pxelinux.0
 LABEL newcfg2
  CONFIG 192.168.1.3::pxe/pxelinux.cfg/default
  APPEND 192.168.1.3::pxe/

Equivalent command lines:

 tftp://192.168.1.3/pxe/pxelinux.0
 tftp://192.168.1.3/pxe/config.c32 tftp://192.168.1.3/pxe/pxelinux.cfg/default tftp://192.168.1.3/pxe/
 
 192.168.1.3::pxe/pxelinux.0
 192.168.1.3::pxe/config.c32 192.168.1.3::pxe/pxelinux.cfg/default 192.168.1.3::pxe/

Bad Heritage on MS DOS disk

§ The wiki prescribes to install SYSLINUX into a normal MS-DOS formatted disk. Depending on the history of your disk or pen drive, it might be "less normal" than needed. You will learn by SYSLINUX failing to boot properly.

This collection of proposals might help if a boot failure is related to unusual partitioning or filesystem format. One possible symptom for such problems can be successfully booting on one machine while failing on another.

Nevertheless, a failure to boot can have many other reasons.

Preparing a normal disk

§ This is a generic procedure to create a mainstream MS-DOS disk:

Make sure to operate on the disk which you want to equip with SYSLINUX.
Make a backup of the disk content. It will be gone after this procedure is done.
Create a new DOS partition table by help of your favorite partitioning tool.
Create a new partition.
Set its "bootable" (or "active") flag.
Format it to FAT16 or FAT32, preferably with LBA addressing.

mkdiskimage

§ There is a tool included in SYSLINUX which shall ease the task of setting up such a disk (image):

Beware: You still need to identify the right disk address and to make your backup before running mkdiskimage!

 Usage: mkdiskimage [-doFMz4][-i id] file c h s (max: 1024 256 63)
  -d    add DOSEMU header
  -o    print filesystem offset to stdout
  -F    format partition as FAT32
  -M    parse "c" argument as megabytes; cylinders are calculated
  -z    use zipdisk geometry (h=64 s=32)
  -4    use 4th partition entry (standard for zipdisks)
  -i    specify the MBR ID
  -s    output a sparse file (don't allocate all blocks)

It invokes mtools to do the actual formatting.

If the number "c" of cylinders is given as 0 (zero), then the program will calculate it from the storage capacity of the disk, depending on the size of the existing image file.

The run may last some time, because the whole resulting partition will be overwritten by 0-bytes before it gets formatted.

Linux examples for mkdiskimage

§ Create a zipdisk-like formatting with FAT32 on disk /dev/sdc with up to 1 GB capacity:

 mkdiskimage -4 -z -F /dev/sdc

HDD-like formatting with FAT16 on disk /dev/sdc with up to 1 GB capacity:

 mkdiskimage /dev/sdc 0 64 32

HDD-like formatting with FAT32 on disk /dev/sdd with more than 1 GB capacity:

 mkdiskimage -F /dev/sdd 0 255 63

Create and format (FAT32) a regular file of 2000 MB as disk image:

offset=$(mkdiskimage -o -F -M my_disk.img 2000 255 63)
printf '%s\n' " Offset for             "
printf '%s\n' "  mount -o loop,offset= "
printf '%s\n' " and for                "
printf '%s\n' "  syslinux -t           "
printf '%s\n' " :                      "
printf '%s\n' "  $offset               "
printf '\n'

More details for experts

§ With persistent problems to boot USB connected pen drives see the section about USB related problems.

Linux EFI kernels

§ Certain kernels have been observed to have issues when loaded with Syslinux on EFI.

Linux EFI nonrelocatable

§ Due to a bug in the configuration system, some EFI kernels are not safely relocatable. CONFIG_EFI now requires CONFIG_RELOCATABLE. Syslinux will (safely) attempt to load such a kernel at its preferred address and bail if the memory is not available. This will likely exhibit itself as working on some platforms while bailing on others (with different memory maps).

Linux EFI pre-3.3

§ Most kernels before Linux-3.3 have also been observed to have other issues. Symptoms include spontaneous reboot at some point after kernel execution begins.

Linux EFI mixed bitness

§ In some cases, users might want to execute a 32bit kernel on a 64bit UEFI system, or viceversa. As of version 6.04-pre1, syslinux.efi can execute a (properly-configured) Linux kernel in EFI "mixed" (CONFIG_EFI_MIXED) mode under the following conditions:

UEFI ia32 (efi32) -> linux32 [OK]
UEFI ia32 (efi32) -> linux64 [FAIL]
UEFI x64 (efi64) -> linux32 [OK]
UEFI x64 (efi64) -> linux64 [OK]