LXR Troubleshooting


  Flag for language en   Flag for language fr 

This is a short list of frequently encountered errors and diagnostics.

This page will be progressively extended with hints and tips according to the feedback gathered from the statistics (mainly which search engine request hit on the LXR site).

You can also participate in improving this page through the Help forum.

Installation

Please reread the installation instructions and check thoroughly each step.

Initialisation

These errors are common to genxref and browsing.

Configuration related errors

Fatal: Couldn't open configuration file xxx

lxr.conf does not exist or cannot be accessed.
The file described by parameter 'filetypeconf' does not exist or cannot be accessed.

lxr.conf must reside in the same directory as the scripts (i.e. diff, ident, search, showconfig and source).
There is no location constraint on the 'filetypeconf' file.
Check also they are at least "world readable".
Fatal: Single tree operation requested and x trees found in configuration file

Parameter 'routing' is set to 'single' and lxr.conf describes several trees.

Edit lxr.conf to solve this inconsistency.
Fatal: Can't find config for xxx

The value of the --url= option must match one of the 'host_names'/'virtroot' combinations, 'baseurl' or 'baseurl_aliases' parameters in lxr.conf. The value of the --tree= option must eventually be equal to the 'treename' parameter of one of the trees.

Check spelling of the genxref line or of your parameters.
Fatal: No file type mapping in xxx
Fatal: No file script interpreter mapping in xxx

lxr.conf and the 'filetypeconf' optional file do not contain 'filetype' or 'interpreters' parameters.

Use the standard files, copy the relevant sections into your custom configuration file or run the configuration wizard.
If you still insist on carving your own configuration file, reread thoroughly the User's Manual.
Fatal: Couldn't make directory xxx

LXR tries to create directories described by parameters 'tmpdir', 'glimpsedir' or 'glimpsedirbase' and 'swishdir' or 'swishdirbase' if they do not exist.

Check that the locations can be reached with write permission by everyone.
Fatal: Both Glimpse and Swish-e have been specified in xxx
Fatal: Neither Glimpse nor Swish-e have been specified in xxx

Both parameters 'glimpsebin' and 'swishbin' have been defined. LXR cannot fancy which one to use for this tree.
Alternatively, none of these parameters have been defined for a tree stored in plain files.

Note: it is possible to run without free-text search. See this tip.
Fix lxr.conf so that one of the parameters is defined.

Database related errors

Fatal: Cant't find database xxx

Parameter 'dbname' incorrectly describes the database (either unsupported storage engine or no storage engine).

Fix lxr.conf.
Fatal: Cant't open connection to database xxx

Database connection is opened with values taken from parameters 'dbname', 'dbuser' and 'dbpass'.

Check these parameters correctly describe the database and grant at least read access. Check also the DB daemon is running and the DB has the correct access rights for the web-server.
Fatal: Can't create Index xxx

Usually preceded by another error, such as Can't open connection to database yyy or by an OS error about a lock or a socket (if it does not print on screen, check the web server log).

Check the database description in lxr.conf and your access rights to the database. Eventually, have you forgotten to activate the DB daemon?
Fatal: Disconnect failed: xxx

An error occurred when disconnecting from the database. It usually means some transactions are still active.

Report it as a bug.

Storage related errors

Fatal: Can't create file access object xxx

This should not happen. If your tree is stored in a Subversion repository, check first the svn binary can be accessed.

Report it as a bug.
Fatal: xxx subprocess died unexpectedly

The task requested from Git, Mercurial (hg) or Subversion (svn) errored out.

Check that the VCS binaries are installed and can be launched by everyone.
Fatal: Error executing "xxx"; rcs not installed? (CVS)

Checking out a file from CVS repository failed.

Check the CVS binaries are installed and can be launched by everyone.
Warning: Oops! Out of sync! (CVS)

CVS differences information need to be reprocessed to attribute each line to the correct revision. LXR lost its marks while analysing a file.

Report it as a bug with a copy of the original CVS file (with extension ,v), not a checked-out copy.

genxref

No matching configuration xxx
No 'sourceroot' for xxx

A tree description in lxr.conf has no 'sourceroot' parameter.

Fix lxr.conf.
Variable 'v' needed to define versions xxx

A tree description in lxr.conf has no 'v' (version) parameter.

Fix lxr.conf.
No version to index

An explicit indexation request with --version=xxx could nout be satisfied. The preceding message explains why.

No corresponding directory xxx in source root

The version is listed in variable 'v' but does not exist in the source tree directory.

Version xxx not listed in lxr.conf, but a directory exists in source root

The version is not listed in variable 'v' but its directory exists in the sources.
This error generally results from a non-finalised version addition. Either fix variable 'v' in lxr.conf or add its directory into the source directory.
No free-text indexing

A free-text search engine is installed but the source-tree is not scanned.

Free-text search and indexing are disabled if the source-tree is stored in a VCS.
Otherwise, neither 'glimpsedir', nor 'glimpsedirbase' have been defined. Fix lxr.conf.
Can't create xxx/.glimpse_exclude (glimpse)

genxref translates the 'ignoredirs' directory exclusion list into a format usable by glimpse. This is only possible if the permissions on the 'glimpsedir' or 'glimpsedirbase' directory allow write access.

Check and eventually change the 'glimpsedir' or 'glimpsedirbase' directory permissions.
Can't open xxx/filenames for writing (swish-e)

genxref creates a file where swish-e can store the names of the files making up the tree. This is only possible if the permissions on the 'swishdir' or 'swishdirbase' directory allow write access.

Check and eventually change the 'swishdir' or 'swishdirbase' directory permissions.
Couldn't exec xxx

An error prevented successful launch of the free-text indexer.

Check 'glimpseindex' or 'glimpsebin' correctly point to the free-text indexer binary.
err: No unique words indexed (swish-e)

swish-e could not find any text to index and this is its weird way to say "File not found".

Check your configuration. Remember that 'sourceroot' directory contains subdirectories with names equal to version names. In the case where you want to cross-reference a single version, you must anyway store it in a subdirectory, however artificial it may seem.
Can't run ctags

An error prevented successful launch of ctags.

Check parameter 'ectagsbin' correctly point to the file parser.
ctags: No files specified. Try "ctags --help"

genxref extracts the correct version of the file from the repository into a temporary file. This copy is only possible if the permissions on the 'tmpdir' directory allow write access.

Check and eventually change the 'tmpdir' directory permissions.
commit ineffective with AutoCommit enabled at lib/LXR/Indexyyy line zzz.

Results from a change in managing strategy for the LXR database.

Can be safely ignored. However, if this happens in release 1.0 and higher, it should be reported as a bug.

Browsing

Blank screen (not even header nor footer)

LXR blew out even before HTTP initialisation was completed. This usually results from bad web server configuration.

The web server was unable to route the URL to LXR, because this URL does not translate to any known LXR service.

If this follows a manual reconfiguration after a switch from single to multiple trees operation (or vice versa), check that you made the appropriate changes in the web-server configuration files apache-lxrserver.conf, lighttpd-lxrserver.conf, nginx-lxrserver.conf or thttpd-lxrserver.conf.
Internal Server Error (HTTP Error 500 with Apache)

Apache access control changed a lot between releases 2.2 and 2.4 introducing backward incompatibility. Your installed version does not match the configuration you made.

Fix manually file .htacess or see this tip.
Warning: Template file xxx does not exist
Warning: Template xxx is not defined

Many browsing actions need a template to lay out their results. In the first case, the relevant configuration parameter is set to point to a non-existent file, while in the second case the parameter is not set at all.

Give the parameter a correct value or create the missing file. Check first the template is defined. Templates are accessed by default from the LXR root directory or your lxr.conf configuration file must be modified to point to your custom location. Eventually, refer to the page on file paths.

Source file or directory display

The directory/file xxx does not exist

If the directory or file does not exist in this version; then, this is not an error.
If the directory or file really exists, it may be banned by an exclusion rule (such as a directory excluded by the 'ignoredirs' configuration array parameters or the –still– undocumented filter function). Otherwise, it means LXR cannot access it.

Check first the access rights to the directory and its ancestors. If they are correct, your tree is not visible to LXR; then check your lxr.conf file. Read also carefully the page on file paths.
xxx cannot be displayed from this browser

You clicked on a graphic file hyperlink.

Either your tree is not visible by the web-server (read carefully the page on file paths, then this configuration rule), or your browser really does not understand the graphics format (eventually change configuration parameter 'graphicfile').

Identifier search

Fatal: Identifier search not available without 'htmlident' template

Search results are shown through a lay-out defined by template 'htmlident'. Without it, nothing can be done.

Check parameter 'htmlident' in lxr.conf and make it point to a valid template file.

Version differences display

Fatal: *** Diff subprocess died unexpectedly

An error occurred during diff GNU utility processing.

Check the error code and report it as a bug.

Free-text search

Warning: Free-text search disabled by configuration file!
Warning: Free-text search not available with VCSs!

Either you configured LXR to run without free-text search, or your source tree is stored in a version control system.

In either case, it is normal behaviour. However, free-text search can be re-enabled in the first case in installing a search engine, setting the relevant configuration parameter(s) and running genxref.
Warning: Free-text search engine required for file search, and no freetext search engine is configured

Some parameter needed for free-text search processing has not been set correctly: 'glimpsebin', 'glimpsedir' or 'glimpsedirbase' or 'swishbin', 'swishdir' or 'swishdirbase'.

Either disable free-text search (see this tip) or set the parameters to the expected values (eventually installing a search engine).
Fatal: Free-text search not available without 'htmlsearch' template

Search results are shown through a lay-out defined by template 'htmlsearch'. Without it, nothing can be done.

Check parameter 'htmlsearch' in lxr.conf and make it point to a valid template file.
Warning: Version xxx has not been indexed and is unavailable for searching

LXR tried to open some search engine internal cache file which appears to be missing. This happens if you add another version to the tree after genxref indexing.

Rerun genxref to index the requested version (or, alternatively, re-index all versions).
Search failed

You attempted a free-text search. The subsequent line is the error message issued by the search engine.

glimpse or swish-e were unable to complete the request. Usually means there are no matches.
Fatal: Glimpse subprocess died unexpectedly

An error occurred during Glimpse free-text search query.

Check the error code and make sure the binary pointed to by parameter 'glimpsebin' is accessible. If you do not find why, report it as a bug.
Unexpected return value x from Glimpse

Glimpse was unable to complete the free-text search query.

If x is 2, files are inaccessible. These usually are the auxiliary caches, which may be missing or have incorrect access rights. The relevant directory is defined by the 'glimpsedir' or 'glimpsedirbase' configuration parameters.

Configuration display

Fatal: Can't display configuration without 'htmlconfig' template

Configuration settings are shown through a lay-out defined by template 'htmlconfig'. Without it, nothing can be done.

Check parameter 'htmlconfig' in lxr.conf and make it point to a valid template file.

Language analysis

Fatal: Unable to load xxx Lang class

File type mapping in parameter 'filetype' associates file extensions to language parsers in the Lang/ subdirectory. None was found for the given language.

If you modified parameter 'filetype' (or, equivalently, file templates/filetype.conf), edit your changes or write the missing parser. Otherwise, report it as a bug.
Fatal: Unable to create xxx Lang object

A preceding message gives the cause of the failure.

If this error occurs alone, report it as a bug.
Fatal: Can't open <generic.conf actual name> (generic parser)

Configuration for the generic parser is stored in file generic.conf (or whatever name you gave in parameter 'genericconf'). The generic parser cannot run without it.

Check the generic parser configuration file is really where parameter 'genericconf' tells it is and that location can be read by everyone.
Fatal: No langid for language xxx (generic parser)

The langid is used to access the relevant keywords and symbols in the database. It is essential to keep things tidy.

If you modified file generic.conf, review your changes or revert to the original file. Otherwise, report it as a bug.

Errors entered in web-server log

Before release 2.0, the web server log was the only source of debugging information. Starting with release 2.0, errors are still entered into the log but they are also displayed on screen, which is more user-friendly.

There are however two kinds of errors which still require log reading:

  1. The first one is the case of an error occurring before LXR has finished intialising its HTTP connection. Nothing can be sent to the screen. Note that this case might be desperate since in a very early error things have not been intialised enough to access the server log.
  2. The second one encompasses all errors directly generated by the Perl interpreter. These are not returned to LXR and cannot be forwarded to the screen.

The most notable errors you may encounter are:

Fatal: sequence (?|...) not recognised in regex

This is a Perl syntax error. The regex (regular expression) dealing with the #include construct and its equivalent in other languages uses a special feature introduced in Perl 5.10. If your Perl interpreter has a lower version, the regex is considered erroneous.

Upgrade your Perl to the latest version. Otherwise install LXR release 0.11 which was downgraded to 5.8-compatible syntax after some non trivial rewriting.
This error should not happen with release 2.0, though full 5.8-compatibility has not been enforced.

Other errors

SELinux alerts when trying to access LXR

Usually caused by an incorrect label on LXR root directory when not installed in /var/www/cgi-bin/.

Relabel the LXR root directory to a type allowing CGI scripts. The most reliable method is to clone /var/www/cgi-bin/ context: $ chcon --reference /var/www/cgi-bin/ -R /LXR/root/directory/
LXR doesn't work with git

genxref and LXR error out when trying to access the git repository.

git support is broken in the standard Perl library. Fixed in 1.0 by module rewriting.
No free-text search with VCSes (CVS, git, …)

You can navigate inside your tree which is located in a VCS repository. But you get errors when you try to use the free-text search feature.

The supported free-text search engines (glimpse and swish-e) know nothing about the format of the VCS repository. They only act on real files. If you are aware of an adequate open-source engine, please suggest its use to the developpers.