Reporting bugs

To report a bug in the BOINC client (or to request a new feature or enhancement) do the following, in the given order:

• Post to the ​BOINC message boards. It may turn out that the bug is known, or is not actually a bug.
• Alternatively, email the ​BOINC Alpha email list. Note: when you post to boinc_alpha, attachments are stripped from your email; include text inline rather than as attachments. There's a 1 MB limit.
• If it's a new bug, create an "issue" on ​the BOINC Github page.

Please include:

• The context: what platform, what version of BOINC, anything else that might be relevant.
• What sequence of actions caused the problem.
• The exact nature of the problem.
• The relevant parts of your message logs (see below).

If you don't include this information, we probably won't be able to fix the bug.. In general we're only interested in bug reports for the current public release, or for the latest testing release.

Crashes

The BOINC client software consists of two programs:

• the client, which runs applications and does network communication;
• the manager, which provides a graphical user interface (GUI) to the client.

On windows, these are called boinc.exe and boincmgr.exe respectively.

Usually if the Manager shows "can't connect" it means the client has crashed. You can verify this as follows. Windows: run the Task Manager (ctrl-shift-esc) and check that there's no process named 'boinc.exe'. Mac/Linux: run ps and check that there's no process named 'boinc'.

If the client or manager crashes, information about the crash is written to a file in the BOINC data directory: stderrgui.txt for the manager, stderrdae.txt for the client. Email David, describing the situation and attaching the relevant file.

The Client Emulator

The most common client problems involve

• work fetch: deciding when to request tasks, what project to request from, and how much work to request.
• task scheduling: deciding what tasks to run at a given point.

The best way to report these types problems is to reproduce them using the ​BOINC Client Emulator, then send us a link to the result. This will allow us to debug the problem on our own computers, which generally makes it easy to fix.

If the emulator doesn't reproduce the bug:

• tell David; we may need to improve the emulator.
• enable the relevant log flags (see below) and send us a segment of the resulting message log. Please point out exactly where you think the client did the wrong thing.

Message logs

If you find a bug or unexpected behavior in the BOINC client, it will help us if you tell BOINC to generate more detailed messages, and then include the message log in your email. To do this, use a text editor like Notepad to create a file cc_config.xml in your BOINC data directory. It has the following form:

<cc_config>
   <log_flags>
       <work_fetch_debug>1</work_fetch_debug>
   </log_flags>
</cc_config>

The work_fetch_debug flag tells BOINC to generate detailed messages about how it decides when to ask projects for jobs.

Have a look at this message log example. Note that each line contains

• The date and time when the message was written.
• The name of the project involved (if any).
• The name of the logging flag.

Many of the logging flags produce large amounts of output, so you should

• enable only the flags that are relevant to the problem you're reporting;
• email us only the range of your message log during which the problem occurred.

(in both cases, it's better to err on the side of including too much).

Some common problem types, and the suggested logging flags, are listed below. You should also check the ​complete list of logging flags.

BOINC gets too much or too little work

<work_fetch_debug>1</work_fetch_debug>

BOINC thinks apps are running but they aren't

<task_debug>1</task_debug>
<cpu_sched_debug>1</cpu_sched_debug>
<mem_usage_debug>1</mem_usage_debug>

CPU benchmark problems

<benchmark_debug>1</benchmark_debug>

Bad task scheduling decisions

<cpu_sched>1</cpu_sched>
<debt_debug>1</debt_debug>
<cpu_sched_debug>1</cpu_sched_debug>

Memory usage and non-BOINC CPU usage

<mem_usage_debug>1</mem_usage_debug>

File transfer problems

<file_xfer_debug>1</file_xfer_debug>
<http_debug>1</http_debug>

Screensaver problems

<scrsave_debug>1</scrsave_debug>

Applications not reporting CPU time, fraction done correctly

<app_msg_receive>1</app_msg_receive>