[[PageOutline]]

= 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 [http://boinc.berkeley.edu/dev/ BOINC message boards].
   It may turn out that the bug is known, or is not actually a bug.
 * Email the [mlist:boinc_alpha 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.'''
 * Create an "issue" on [https://github.com/BOINC/boinc/issues the BOINC Github page].
 * Email [ProjectPeople David Anderson].

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 [ProjectPeople David and Rom],
describing the situation and attaching the relevant file.

== Work-fetch and task scheduling bugs ==

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
[http://boinc.berkeley.edu/dev/sim_web.php 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 [ProjectPeople 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 [//stdoutdae.txt 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 [http://boinc.berkeley.edu/wiki/Client_configuration#Logging_flags 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>
}}}