# Troubleshooting the Installation Process

## Reliability of optical media

Sometimes, especially with older drives, the installer may fail to boot from an optical disc. The installer may also — even after booting successfully from such disc — fail to recognize the disc or return errors while reading from it during the installation.

There are many different possible causes for these problems. We can only list some common issues and provide general suggestions on how to deal with them. The rest is up to you.

There are two very simple things that you should try first.

- If the disc does not boot, check that it was inserted correctly and that it is not dirty.

- If the installer fails to recognize the disc, try just running the option Detect and mount installation media a second time. Some DMA related issues with very old CD-ROM drives are known to be resolved in this way.

If this does not work, then try the suggestions in the subsections below. Most, but not all, suggestions discussed there are valid for CD-ROM and DVD.

If you cannot get the installation working from optical disc, try one of the other installation methods that are available.

### Common issues

- Some older CD-ROM drives do not support reading from discs that were burned at high speeds using a modern CD writer.

- Some very old CD-ROM drives do not work correctly if direct memory access (DMA) is enabled for them.

### How to investigate and maybe solve issues

If the optical disc fails to boot, try the suggestions listed below.

- Check that your BIOS/UEFI actually supports booting from optical disc (only an issue for very old systems) and that booting from such media is enabled in the BIOS/UEFI.

- If you downloaded an iso image, check that the md5sum of that image matches the one listed for the image in the `MD5SUMS` file that should be present in the same location as where you downloaded the image from.

      $ md5sum debian-testing-i386-netinst.iso
      a20391b12f7ff22ef705cee4059c6b92  debian-testing-i386-netinst.iso

  Next, check that the md5sum of the burned disc matches as well. The following command should work. It uses the size of the image to read the correct number of bytes from the disc.

      $ dd if=/dev/cdrom | \
      > head -c `stat --format=%s debian-testing-i386-netinst.iso` | \
      > md5sum
      a20391b12f7ff22ef705cee4059c6b92  -
      262668+0 records in
      262668+0 records out
      134486016 bytes (134 MB) copied, 97.474 seconds, 1.4 MB/s

If, after the installer has been booted successfully, the disc is not detected, sometimes simply trying again may solve the problem. If you have more than one optical drive, try changing the disc to the other drive. If that does not work or if the disc is recognized but there are errors when reading from it, try the suggestions listed below. Some basic knowledge of &arch-kernel; is required for this. To execute any of the commands, you should first switch to the second virtual console (VT2) and activate the shell there.

- Switch to VT4 or view the contents of `/var/log/syslog` (use `nano` as editor) to check for any specific error messages. After that, also check the output of `dmesg`.

- Check in the output of `dmesg` if your optical drive was recognized. You should see something like (the lines do not necessarily have to be consecutive):

      ata1.00: ATAPI: MATSHITADVD-RAM UJ-822S, 1.61, max UDMA/33
      ata1.00: configured for UDMA/33
      scsi 0:0:0:0: CD-ROM            MATSHITA DVD-RAM UJ-822S  1.61 PQ: 0 ANSI: 5
      sr0: scsi3-mmc drive: 24x/24x writer dvd-ram cd/rw xa/form2 cdda tray
      cdrom: Uniform CD-ROM driver Revision: 3.20

  If you don't see something like that, chances are the controller your drive is connected to was not recognized or may be not supported at all. If you know what driver is needed for the controller, you can try loading it manually using `modprobe`.

- Check that there is a device node for your optical drive under `/dev/`. In the example above, this would be `/dev/sr0`. There should also be a `/dev/cdrom`.

- Use the `mount` command to check if the optical disc is already mounted; if not, try mounting it manually:

      $ mount /dev/hdc /cdrom

  Check if there are any error messages after that command.

- Check if DMA is currently enabled:

      $ cd /proc/ide/hdc
      $ grep using_dma settings
      using_dma      1       0       1       rw

  A 1 in the first column after `using_dma` means it is enabled. If it is, try disabling it:

      $ echo -n "using_dma:0" >settings

  Make sure that you are in the directory for the device that corresponds to your optical drive.

- If there are any problems during the installation, try checking the integrity of the installation media using the option near the bottom of the installer's main menu. This option can also be used as a general test if the disc can be read reliably.

## Boot Configuration

If you have problems and the kernel hangs during the boot process, doesn't recognize peripherals you actually have, or drives are not recognized properly, the first thing to check is the boot parameters, as discussed in boot-parms.

In some cases, malfunctions can be caused by missing device firmware (see hardware-firmware and loading-firmware).

## Software Speech Synthesis

If software speech synthesis does not work, there is most probably an issue with your sound board, usually because either the driver for it is not included in the installer, or because it has unusual mixer level names which are set to muted by default. You should thus submit a bug report which includes the output of the following commands, run on the same machine from a Linux system which is known to have sound working (e.g., a live CD).

- `dmesg`

- `lspci`

- `lsmod`

- `amixer`

## Common &arch-title; Installation Problems

There are some common installation problems that can be solved or avoided by passing certain boot parameters to the installer.

If your screen begins to show a weird picture while the kernel boots, eg. pure white, pure black or colored pixel garbage, your system may contain a problematic video card which does not switch to the framebuffer mode properly. Then you can use the boot parameter `vga=normal nomodeset` to disable the framebuffer console. Only a reduced set of languages will be available during the installation due to limited console features. See boot-parms for details.

### System Freeze During the PCMCIA Configuration Phase

Some very old laptop models produced by Dell are known to crash when PCMCIA device detection tries to access some hardware addresses. Other laptops may display similar problems. If you experience such a problem and you don't need PCMCIA support during the installation, you can disable PCMCIA using the `hw-detect/start_pcmcia=false` boot parameter. You can then configure PCMCIA after the installation is completed and exclude the resource range causing the problems.

Alternatively, you can boot the installer in expert mode. You will then be asked to enter the resource range options your hardware needs. For example, if you have one of the Dell laptops mentioned above, you should enter `exclude port 0x800-0x8ff` here. There is also a list of some common resource range options in the System resource settings section of the PCMCIA HOWTO. Note that you have to omit the commas, if any, when you enter this value in the installer.

## Interpreting the Kernel Startup Messages

During the boot sequence, you may see many messages in the form `can't find `something``, or ``something` not present`, `can't initialize `something``, or even `this driver release depends on `something``. Most of these messages are harmless. You see them because the kernel for the installation system is built to run on computers with many different peripheral devices. Obviously, no one computer will have every possible peripheral device, so the operating system may emit a few complaints while it looks for peripherals you don't own. You may also see the system pause for a while. This happens when it is waiting for a device to respond, and that device is not present on your system. If you find the time it takes to boot the system unacceptably long, you can create a custom kernel later (see kernel-baking).

## Reporting Installation Problems

If you get through the initial boot phase but cannot complete the install, the menu option Save debug logs may be helpful. It lets you store system error logs and configuration information from the installer on a storage medium, or download them using a web browser. This information may provide clues as to what went wrong and how to fix it. If you are submitting a bug report, you may want to attach this information to the bug report.

Other pertinent installation messages may be found in `/var/log/` during the installation, and `/var/log/installer/` after the computer has been booted into the installed system.

## Submitting Installation Reports

If you still have problems, please submit an installation report (in English please, whenever possible). We also encourage installation reports to be sent even if the installation is successful, so that we can get as much information as possible on the largest number of hardware configurations.

Note that your installation report will be published in the Debian Bug Tracking System (BTS) and forwarded to a public mailing list. Make sure that you use an e-mail address that you do not mind being made public.

If you have a working &debian; system, the easiest way to send an installation report is to install the `installation-report` and `reportbug` packages (`apt install installation-report reportbug`), configure `reportbug` as explained in mail-outgoing, and run the command `reportbug installation-reports`.

Alternatively you can use this template when filling out installation reports, and file the report as a bug report against the `installation-reports` pseudo package, by sending it to submit@bugs.debian.org.

    Package: installation-reports

    Boot method: <How did you boot the installer? CD/DVD? USB stick? Network?>
    Image version: <Full URL to image you downloaded is best>
    Date: <Date and time of the install>

    Machine: <Description of machine (eg, IBM Thinkpad R32)>
    Processor:
    Memory:
    Partitions: <df -Tl will do; the raw partition table is preferred>

    Output of lspci -knn (or lspci -nn):

    Base System Installation Checklist:
    [O] = OK, [E] = Error (please elaborate below), [ ] = didn't try it

    Initial boot:           [ ]
    Detect network card:    [ ]
    Configure network:      [ ]
    Detect media:           [ ]
    Load installer modules: [ ]
    Detect hard drives:     [ ]
    Partition hard drives:  [ ]
    Install base system:    [ ]
    Clock/timezone setup:   [ ]
    User/password setup:    [ ]
    Install tasks:          [ ]
    Install boot loader:    [ ]
    Overall install:        [ ]

    Comments/Problems:

    <Description of the install, in prose, and any thoughts, comments
          and ideas you had during the initial install.>

    Please make sure that any installation logs that you think would
    be useful are attached to this report. (You can find them in the installer
    system in /var/log/ and later on the installed system under
    /var/log/installer.) Please compress large files using gzip.

In the bug report, describe what the problem is, including the last visible kernel messages in the event of a kernel hang. Describe the steps that you did which brought the system into the problem state.