0 — Directory Structure and Configuration

8. Common Errors

If Circos halts with an error, before contacting me or posting to the discussion group, read the following pages to diagnose the problem.

To help you diagnose the problem, use Circos' debugging facility to track the program as it runs.

If you still cannot resolve the issue, please write to the discussion group. Make sure to include the error report and any relevant configuration file components. If you don't know where to start, make your configuration and data files available for others so that they can help you debug the problem.

contacting me

If you are unable to obtain an answer from the discussion group, or are pressed for time, contact me. Because I get a lot of direct requests, the more you help me diagnose your problem the faster I can respond and help you.

When you contact me please be specific about what is happening, why you think it should not be happening, and what you expect to happen. Include debug output and all your configuration and data files in your email so that I can reproduce the problem.

If you are successful in creating an image, but find that it is not what you expect please send me the image.

common errors and problems

Perl on Windows — can't figure it out?

If you are running Circos on Windows, you may be unfamiliar with Perl. Please read the Windows vs UNIX tutorial before you read the Distribution and Installation tutorial.

There are plenty of excellent Perl tutorials online for both UNIX and Windows. Make use of them. Remember, you don't need to know any Perl, only how to install it and call it to run Circos.

Circos errors

This is what a typical Circos error looks like. I have tried to make them reasonably self-explanatory.

  *** CIRCOS ERROR ***

  CONFIGURATION FILE ERROR

  You did not define a karyotype file. Are you sure your configuration file is
  well formed?

  If you are having trouble debugging this error, use this tutorial to learn how
  to use the debugging facility

      http://www.circos.ca/tutorials/lessons/configuration/debugging

  If you're still stumped, get support in the Circos Google Group

      http://groups.google.com/group/circos-data-visualization

  Stack trace:
 at /home/martink/work/circos/svn/bin/../lib/Circos/Error.pm line 271
	Circos::Error::fatal_error('configuration', 'no_karyotype') called at 
           /home/martink/work/circos/svn/bin/../lib/Circos/Configuration.pm line 468
	Circos::Configuration::validateconfiguration() called at 
           /home/martink/work/circos/svn/bin/../lib/Circos.pm line 149
	Circos::run('Circos') called at /home/martink/bin/circos line 229

configuration file import

If you are importing configuration files using <<include>>, make sure you understand how the path resolution works. This is described in the Configuration Files tutorial.

missing units

Many configuration parameters require units (see tutorial 1.2). An error like this

  Unable to convert a value [0.005] from one unit [n] to another [b]. The
  following from->to combinations were expected: r->b u->b

means that the value 0.005 was expected to have a unit "r" (relative) or "u" (chromosome unit) for conversion to "b" (base), but was foudn to have unit "n" (explicit code for no unit).

If you do not define a required parameter the error will look like this

  The parameter [ideogram/thickness] was not defined. It needs to be defined and
  have one of these units [r,p].

slow performance

Some parts of the code are less (or more) optimized than others. In particular, text tracks can take a long time to render.

Turn on benchmarking using -debug_group timer to time the code. See the Debugging tutorial for more information.

If you are wondering what is happening as Circos is running, use -debug_group _all to turn on all debugging. This will create a lot of output.