Debugging Central

This page is part of the debugging series — pages with debugging details for a variety of Ubuntu packages.


Update-manager provides two services - the ability to upgrade packages within a release, and the ability to upgrade a release of Ubuntu to the next one. When looking at bug reports it is important to keep this in mind and identify whether it is a problem with a package upgrade or a release upgrade.

If there is a log attached to the bug (that should be default for gutsy2hardy upgrade failures) then check the main.log first and scroll right to the end. The error should be right there. If its a error from a package, then check out the term.log and search for "dpkg: error", that should have some additional information about the problem.

Some information about bugs in packages and not update-manager itself can be found at DebuggingInstallationIssues.

How to file

When filing a bug report regarding a problem with a distribution or release upgrade at a minimum you should add every file in '/var/log/dist-upgrade/', there should be at least 3, as separate attachments. You should also tag your distribution upgrade bug with the release you are moving from and to - for example 'feisty2gutsy'.

Bug Tags


Use case


Bugs related to upgrades from Lucid Lynx (10.04) to Precise Pangolin (12.04).


Bugs related to an upgrade from CD-ROM or DVD media.

The previously described tags are specific to the UpdateManager application, if you need more general tags please visit Bugs/Tags page.

Debugging Procedures

For a distribution upgrade, in /var/log/dist-upgrade/ there are three log files that are helpful in debugging the issue:

  1. 'main.log'
    • contains the version of release upgrade and the lsb-release (version of Ubuntu)
    • contains information on how /etc/apt/sources.list was handled and updated

    • contains log information regarding the free space calculation
    • contains an overview of the whole process
    • may contain python back traces
    • this is the first place to search for a failure
  2. 'apt.log'
    • contains a dump of the package problem resolver
    • it is useful when update-manager says it can not upgrade
    • it is also useful for identifying 3rd party repositories that are problematic
    • it usually reveals information about incorrect dependencies
  3. 'term.log'
    • is a subset of /var/log/apt/term.log

    • contains detailed informations about the failure found in main.log
    • errors can be found by looking for the string 'dpkg: error'

How to Triage

Help with triaging bugs for update-manager is very welcome. It accumulated a lot of reports over time. Some are bugs in update-manager, but some are bugs in packages where update-manager is just the messenger. To find out what exactly is the problem, we always need the log files in /var/log/dist-upgrade/*. Most of the time they provide enough information to know what went wrong. If they are missing, it is recommended to ask for them with a phrase like:

Thanks for taking the time to report this bug and helping to make Ubuntu better. Could you please add the log files from '/var/log/dist-upgrade/' to this bug report as separate attachments? Thanks in advance.

If the problem is with update-manager itself, then there is only the file /var/log/apt/term.log attached to the report and the report is tagged apport-package.

To find out what is the problem, start by looking for the string ' ERROR' in main.log. If the log shows that the problem is a error from dpkg when processing a package then search term.log for details about the failure.
In the case of a package failure, copy the name of the package that failed the main.log, open term.log and search for that name until you find a line like 'dpkg: error' (it may differ if the logs are not in english)
Then please reassign the bug to the package that failed during the upgrade. Also add the relevant lines from when the package failed (found in term.log) as a comment to the bug.

Note about package reassignment:
Carefully read and understand the error message before affecting a report from update-manager to another package. The package that failed is not always the primary cause of a failure. For instance many issues are caused by debconf (ex bug 349469), shadow (ex bug 238755), ucf (ex bug 269539), a system error, ... If it's a system error, then there is no need to reassign to the package that failed because it is not its fault

How to Forward

Forwarding of update-manager bugs upstream is not necessary as update-manager is only used by Ubuntu and there is not a traditional upstream.


  • When running a development release of Ubuntu you will frequently receive messages when trying to run update-manager that it could not calculate the upgrade. This is expected and happens due to the amount of changes occurring in the repository.
  • Occasionally update-manager will indicate that it received a 403 message when trying to retrieve a package. If this message occurs when trying to retrieve a package from or this can be due to a regression in a package that was available there and was subsequently removed. If this message is received when trying to retrieve a package from a mirror it is probably an issue with that mirror.
  • The distribution upgrade will warn the user if there is not enough free space on any partition (e.g. '/boot') on their system. The space must be freed and the upgrade restarted.

CategoryBugSquad CategoryDebugging

DebuggingUpdateManager (last edited 2014-12-07 22:23:09 by penalvch)