Common Problems

From Syslinux Wiki
Revision as of 01:39, 19 August 2011 by GeneC (talk | contribs) (Modules: Details)

Jump to: navigation, search

Windows Vista/Windows 7 chainloading

Windows Vista and Windows 7 refuse to hibernate if it is chainloaded. Instead, you have to chainload Syslinux from Windows BCD. There is no known workaround for this.

Watch the name of your kernel

The single most common user error is setting up a kernel configuration which uses 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 extension bites a lot of people:

  • .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: SYSLINUX#KERNEL_file

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.


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 0 to 3 characters. The characters are interpreted in a case-insensitive manner and stored as uppercase. The dot may be omitted if the extension is 0 characters. The character set is restrictive within an 8-bit character set and include A-Z, 0-9, "_", and "~", among others. See also for more details.


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.

See also


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 
-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.


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 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 
-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 that 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 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 for more information

Official Binaries

If you've 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's always recommended that you try the latest version but you should at least try the official binaries from the same version if you don't wish to try the latest version. 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're not using the current version.

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

make clean
make installer

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

  1. 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.
  2. 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 need to wait for a download even. If there is a genuine issue, this aids in diagnosing the issue.


Modules, especially COM32 modules (.c32 files), should ideally come from the same package as the core binaries (isolinux.bin, ldlinux.sys, pxelinux.0) that you're 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/builtin COMBOOT API.

Incorrect Syntax

Incorrect syntax in configuration files is another common error. If you aren't getting the menu or results you expect double check 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.

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 with the Syslinux boot-loader installed that you are expecting to boot, 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 one has to enable the bootflag 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 one has to use "sgdisk" to get this task done.

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

 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 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. in 4.00 - 4.03 is broken. PXELINUX 4.04 solves this issue.

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

A second partial and heavily manual workaround (if you're 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 currently 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://
LABEL newcfg1
	CONFIG tftp://
	APPEND tftp://

LABEL newpxe2
LABEL newcfg2

Equivalent command lines:

tftp:// tftp:// tftp://