<chapter id="admin.troubleshooting">
	<title>Troubleshooting</title>

	<para>This chapter provides the Administrator with additional information
	related to Application Errors and common problems in MantisBT.
	</para>

	<para>Useful additional reference information and support may also be
	found on the <ulink url="http://www.mantisbt.org/">MantisBT website</ulink>,
	more specifically the <ulink url="http://www.mantisbt.org/forums/">Forums</ulink>
	and the <ulink url="http://www.mantisbt.org/bugs/">Bugtracker</ulink>.
	</para>

	<section id="admin.troubleshooting.errors">
		<title>Application Errors</title>

		<para>Additional information about MantisBT common errors.
		</para>

		<section id="admin.troubleshooting.errors.1502">
			<title>Error 1502 - Category not found</title>

			<para>This error occurs whenever MantisBT tries to access an
				issue having a Category which has been deleted from the
				database.
			</para>
			<para>It will most likely happen when the Category specified by
				<link linkend="admin.config.defaults">$g_default_category_for_moves</link>
				has been deleted, and an issue is subsequently moved to another
				project where its current category does not exist.
			</para>

			<para>There are two ways to resolve this issue:
				<orderedlist>
					<listitem><para>Recreate the missing category
						</para>
						<itemizedlist>
							<listitem><para>Find the missing Category's Id</para>
								<para>This can be done by checking the value of
									<emphasis>default_category_for_moves</emphasis>
									in config_inc.php and/or in Manage Configuration.
									Alternatively, the following SQL can be executed
									<programlisting>SELECT DISTINCT category_id
FROM mantis_bug_table b
LEFT OUTER JOIN mantis_category_table c ON category_id = c.id
WHERE category_id &lt;&gt; 0
AND c.id IS NULL
</programlisting>
								</para>
							</listitem>

							<listitem><para>Recreate the missing Category</para>
								<para>The category's id must be manually set to
									reflect the value retrieved above (e.g. using SQL
									or your favorite DB admin tool)
								</para>
							</listitem>
						</itemizedlist>
					</listitem>

					<listitem><para>Assign a new category to the issues
						referencing the missing one
						</para>
						<itemizedlist>
							<listitem><para>Identify the corrupted issues
								and corresponding missing categories
								</para>
								<programlisting>SELECT b.id, category_id
FROM mantis_bug_table b
LEFT OUTER JOIN mantis_category_table c ON category_id = c.id
WHERE category_id &lt;&gt; 0
AND c.id IS NULL
</programlisting>
							</listitem>

							<listitem><para>Determine which Category id to use
								instead of the deleted one</para>
							</listitem>

							<listitem><para>Update the issues</para>
								<para>This can either be done manually using
									your favorite DB admin tool or with SQL, e.g.
									<programlisting>UPDATE mantis_bug_table
SET category_id = (NewCategoryId)
WHERE category_id = (OldCategoryId)
</programlisting>
								</para>
							</listitem>
						</itemizedlist>
					</listitem>
				</orderedlist>
			</para>

			<para>Finally, to avoid future occurences, you need to set
				<link linkend="admin.config.defaults">$g_default_category_for_moves</link>
				to a valid Category Id.
				This must be done as appropriate, either globally in
				config_inc.php, or via the Manage Configuration page,
				for all occurences of the parameter.
			</para>

			<para>Note: to retrieve a category's ID, you can either
				<itemizedlist>
					<listitem><para>Look up the value directly in the database:
						mantis_category_table, column 'id'
						</para>
					</listitem>
					<listitem><para>Go to Manage Projects, click the
						<emphasis>Edit</emphasis> button for the desired category
						and look for the the value next to 'id=' in the page's URL
						</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>

		<section id="admin.troubleshooting.errors.2800">
			<title>Error 2800 - Invalid form security token</title>

			<para>This error may only occur when Form Validation is enabled with
			<link linkend="admin.config.webserver">$g_form_security_validation</link> = ON.
			There are several known cases that could trigger it:
				<itemizedlist>
					<listitem><para>Multiple submissions of a form by clicking
						on the submit button several times (user error)</para>
					</listitem>
					<listitem><para>Invalid or unauthorized submission of a
						form, e.g. by hand-crafting the URL (CSRF attack)</para>
					</listitem>
					<listitem><para>Expired PHP session</para>
					</listitem>
				</itemizedlist>
				In the first two instances, MantisBT's behavior is by design, and
				the response as expected.
				For expired sessions however, the user is impacted by system behavior, which
				could not only cause confusion, but also potential loss of submitted form data.
				What happens is driven by several php.ini configuration settings:
				<itemizedlist>
					<listitem><para>The ratio
						<ulink url="http://php.net/session.gc-probability">
							session.gc_probability</ulink>
						divided by
						<ulink url="http://php.net/session.gc-divisor">
							session.gc_divisor</ulink>,
						which determines the probability that the garbage collection process
						will start when a session is initialized.
						</para>
					</listitem>
					<listitem><para>
						<ulink url="http://php.net/session.gc-maxlifetime">
							session.gc_maxlifetime</ulink> which specifies (as the name does not indicate)
							the <emphasis>minimum</emphasis> validity of session data.
						</para>
					</listitem>
				</itemizedlist>
				With PHP default values, sessions created more than 1440 seconds (24 minutes) ago
				have a 1% chance to be invalidated each time a new session is initialized.
				This explains the seemingly random occurence of this error.
			</para>

			<para>Unfortunately, this problem cannot be fixed without a major rework of the way sessions and
			form security are handled in MantisBT.
			</para>

			<para>As a workaround, the Administrator can
				<itemizedlist>
					<listitem><para>Increase the value of
						<ulink url="http://php.net/session.gc-maxlifetime">session.gc_maxlifetime</ulink></para>
					</listitem>
					<listitem><para>Set <link linkend="admin.config.webserver">
						$g_form_security_validation</link> = OFF.
						<emphasis>Note that for security reasons, it is strongly recommended not to do this.</emphasis>
						</para>
					</listitem>
				</itemizedlist>
			Users may also install local tools to avoid loss of form data, e.g.
			<ulink url="http://lazarus.interclue.com/">Lazarus Form Recovery</ulink>
			add-on for Firefox.
			</para>

			<para>Further references and reading:
				<itemizedlist>
					<listitem>
						<para>MantisBT issues
						<ulink url="http://www.mantisbt.org/bugs/view.php?id=12381">12381</ulink>,
						<ulink url="http://www.mantisbt.org/bugs/view.php?id=12492">12492</ulink>,
						<ulink url="http://www.mantisbt.org/bugs/view.php?id=13106">13106</ulink>,
						<ulink url="http://www.mantisbt.org/bugs/view.php?id=13246">13246</ulink>
						</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

</chapter>
