@c This is part of the AUCTeX Manual.
@c Copyright (C) 2004-2025 Free Software Foundation, Inc.
@c See the file auctex.texi for copying conditions.

@c We should switch to sectioning commands instead of items when this
@c list grows.  Keep in mind to formulate short questions because
@c section headings will not be broken in contrast to items.
@enumerate
@item
Something is not working correctly.  What should I do?

If you are having trouble with upgrading @acronym{ELPA} package, first
have a look at the dedicated entry below.  If that doesn't resolve your
issue, then come back here and proceed.

Well, you might have guessed it, the first place to look is in the
available documentation packaged with @AUCTeX{}.  This could be the
@file{README} file or @file{NEWS.org} file in case you are experiencing
problems after an upgrade, the section about bugs in the manual in case
you encountered a bug or the relevant sections in the manual for other
related problems.

If this did not help, you can send a bug report to the @AUCTeX{} bug
reporting list by using the command @kbd{M-x TeX-submit-bug-report @key{RET}}.
But before you do this, you can try to get more information about the
problem at hand which might also help you locate the cause of the error
yourself.

First, you can try to generate a so-called backtrace which shows the
functions involved in a program error.  In order to do this, start Emacs
with the command line @samp{emacs --debug-init} and/or put the line

@lisp
(setq debug-on-error t)
@end lisp

as the first line into your init file.  After Emacs has started, you can
load a file which triggers the error and a new window should pop up
showing the backtrace.  If you get such a backtrace, please include it
in the bug report.

Second, you can try to figure out if something in your personal or site
configuration triggers the error by starting Emacs without such
customizations.  You can do this by invoking Emacs with the following
command line:
@example
emacs -q -no-site-file --eval "(progn (package-initialize t)
(package-activate 'auctex))"
@end example
Use @samp{runemacs} instead of @samp{emacs} on @w{MS Windows}.

The @option{--eval} option activates only @AUCTeX{} among all installed
@acronym{ELPA} packages.

After you have started Emacs like this, you can load the file triggering
the error.  If everything is working now, you know that you have to
search either in the site configuration file or your personal init file
for statements related to the problem.

@item
@acronym{ELPA} upgrade fails.  What should I do?

In general, @acronym{ELPA} upgrade can fail in a Emacs session you are
running, especially when @AUCTeX{} major version increases.  This entry
covers the following cases in such casual upgrade.
@itemize
@item
Upgrade stops with error and doesn't complete.
@item
Upgrade falls in infinite loop and doesn't terminate.  You have
to interrupt it with @kbd{C-g} and upgrade doesn't complete.
@item
It looks like upgrade finishes successfully but afterwards @AUCTeX{}
breaks with mysterious error like:
@example
TeX-command-expand: Wrong type argument: stringp, nil
@end example

@end itemize

These issues involve byte compilation failure.  In the third case, the
generated @file{.elc} files are actually corrupted.  Thus the point is to
have sane byte compilation.

The first thing which is worth trying is:
@enumerate
@item
Terminate the current running Emacs session and restart Emacs.
@item
Type @kbd{M-x package-recompile @key{RET} auctex @key{RET}}.
@item
Restart your Emacs again.
@end enumerate

If you are lucky enough, this will basically resolve the issue.  There is
still old @samp{auctex-X.Y.Z} directory left behind under
@file{~/.emacs.d/elpa/}, so delete it manually to avoid future trouble.

If the above prescription doesn't work, then try:
@enumerate
@item
Uninstall @AUCTeX{} once.
@item
Restart your Emacs and (before doing anything else) reinstall @AUCTeX{}.
@end enumerate

In theory, this recipe will circumvent all caveats in @acronym{ELPA}
upgrade of @AUCTeX{}.  Find and delete old @samp{auctex-X.Y.Z} directory
remaining under @file{~/.emacs.d/elpa/}.

@item
What versions of Emacs are supported?

@AUCTeX{} was tested with @w{GNU Emacs 28.1}.  Older versions may work but
are unsupported.

@item
Why doesn't the completion, style file, or multifile stuff work?

It must be enabled first, insert this in your init file:

@lisp
(setq-default TeX-master nil)
(setq TeX-parse-self t)
(setq TeX-auto-save t)
@end lisp

Read also the chapters about parsing and multifile documents in the
manual.
@xref{Parsing Files} and @ref{Multifile}.

@item
Why doesn't @code{TeX-save-document} work?

@code{TeX-check-path} has to contain "@file{./}" somewhere.

@item
Why is the information in @file{foo.tex} forgotten when I save
@file{foo.bib}?

For various reasons, @AUCTeX{} ignores the extension when it stores
information about a file, so you should use unique base names for your
files.  E.g.@: rename @file{foo.bib} to @file{foob.bib}.

@item
Why doesn't @AUCTeX{} signal when processing a document is done?

If the message in the minibuffer stays "Type `C-c C-l' to display
results of compilation.", you probably have a misconfiguration in your
init file (@file{.emacs}, @file{init.el} or similar).  To track this
down either search in the @samp{*Messages*} buffer for an error message
or put @code{(setq debug-on-error t)} as the first line into your init
file, restart Emacs and open a @LaTeX{} file.  Emacs will complain
loudly by opening a debugging buffer as soon as an error occurs.  The
information in the debugging buffer can help you find the cause of the
error in your init file.

@item
Why does @code{TeX-next-error} (@kbd{C-c `}) fail?

If @code{TeX-file-line-error} is set to @code{nil} (not the default),
these sort of failures might be related to the the fact that when writing
the log file, @TeX{} puts information related to a file, including error
messages, between a pair of parentheses.  In this scenario @AUCTeX{}
determines the file where the error happened by parsing the log file and
counting the parentheses.  This can fail when there are other, unbalanced
parentheses present.

Activating so-called @samp{file:line:error} messages for the log file usually
solves this issue, as these kind of messages are are easier to parse;
however, they may lack some details.  Activation can be done either in
the configuration of your @TeX{} system (consult its manual to see where
this is) or by simply keeping the variable @code{TeX-file-line-error} to
the default value of non-@code{nil}.

@item
What does @samp{AUC} stand for?

@AUCTeX{} came into being at Aalborg University in Denmark.  Back then
the Danish name of the university was Aalborg Universitetscenter; @samp{AUC}
for short.

@end enumerate
