All Manuals > LispWorks Release Notes and Installation Guide > 14 Troubleshooting, Patches and Reporting Bugs


14.10 Reporting bugs

If you discover a bug, in either the software or the documentation, you can submit a bug report by any of the following routes.

The addresses are listed in Send the bug report. Please note that we much prefer email.

14.10.1 Check for existing fixes

Before reporting a bug, please ensure that you have the latest patches installed and loaded. Visit for the latest patch release.

If the bug persists, check the Lisp Knowledgebase at for information about the problem - we may already have fixed it or found workarounds.

If you need informal advice or tips, try joining the LispWorks users' mailing list. Details are at .

14.10.2 Performance Issues

If the problem is poor performance, you should use room, extended-time and profile to check what actually happens. See the LispWorks User Guide and Reference Manual for details of these diagnostic functions and macros.

If this does not help you to resolve the problem, submit a report to Lisp Support (see next section) and attach the output of the diagnostics.

14.10.3 Generate a bug report template

Whatever method you want to use to contact us, choose Help > Report Bug from any tool, or use the command Meta+X Report Bug, or at a Lisp prompt, use :bug-form, for example:

:bug-form "foo is broken" :filename "bug-report-about-foo.txt"

All three methods produce a report template you can fill in. In the GUI environment we prefer you use the Report Bug command - do this from within the debugger if an error has been signalled.

The bug report template captures details of the Operating System and Lisp you are running, as well as a stack backtrace if your Lisp is in the debugger. There may be delays if you do not provide this essential information.

If the issue you are reporting does not signal an error, or for some other reason you are not able to supply a backtrace, we still want to see the bug report template generated from the relevant LispWorks image.

14.10.4 Add details to your bug report

Under 'Urgency' tell us how urgent the issue is for you. We classify reports as follows:


A bug or missing feature that is stopping progress. Probably needs a private patch, possibly under a support contract, unless a workaround can be found.

Current Release

Either a fix in the next patch bundle or as a private patch, possibly under a support contract.

Next Release

A fix would be nice in the next minor release.

Future Release

An item for our wishlist.


Probably not a bug or feature request.

Tell us if the bug is repeatable. Add instructions on how to reproduce it to the 'Description' field of the bug report form.

Include any other information you think might be relevant. This might be your code which triggers the bug. In this case, please send us a self-contained piece of code which demonstrates the problem (this is much more useful than code fragments).

Include the output of the Lisp image. In general it is not useful to edit the output, so please send it as-is. Where output files are very large (> 2MB) and repetitive, the first and last 200 lines might be adequate.

If the problem depends on a source or resource file, please include that file with the bug report.

If the bug report falls into one of the categories below, please also include the results of a backtrace after carrying out the extra steps requested:

14.10.5 Reporting crashes

Very occasionally, there are circumstances where it is not possible to generate a bug report form from the running Lisp which has the bug. For example, a delivered image may lack the debugger, or the bug may cause lisp to crash completely. In such circumstances:

  1. It is still useful for us to see a bug report form from your lisp image so that we can see your system details. Generate the form before your code is loaded or a broken call is made, and attach it to your report.
  2. Create a file init.lisp which loads your code that leads to the crash.
  3. Run LispWorks with init.lisp as the initialization file and with output redirected to a file. For example, on Mac OS X:
  4. % "/Applications/LispWorks 7.0 (32-bit)/LispWorks (32-bit).app/Contents/MacOS/lispworks-7-0-0-x86-darwin" -init init.lisp > lw.out

    where % denotes a Unix shell prompt.

    On Windows:

    C:\> "Program Files\LispWorks\lispworks-7-0-0-x86-win32.exe" -init init.lisp > lw.out

    where C:\> denotes the prompt in a MS-DOS command window.

    On Linux:

    % /usr/bin/lispworks-7-0-0-x86-linux -init init.lisp > lw.out

    where % denotes a Unix shell prompt.

    On UNIX (SPARC in this example):

    % /usr/lib/lispworks/lib/7-0-0-0/config/lispworks- 7-0-0 -sparc-solaris -init init.lisp > lw.out
  5. Attach the lw.out file to your report. In general it is not useful to edit the output of your Lisp image, so please send it as-is. Where output files are very large (> 2MB) and repetitive, the first and last 200 lines might be adequate.

14.10.6 Log Files

If your application writes a log file, add this to your report. If your application does not write a log file, consider adding it, since a log is always useful. The log should record what the program is doing, and include the output of (room) periodically, say every five minutes.

You can make the application write a bug form to a log file automatically by making your error handlers call dbg:log-bug-form.

14.10.7 Reporting bugs in delivered images

Some delivered executables lack the debugger. It is still useful for us to see a bug report template from your Lisp image that was used to build the delivered executable. If possible, load your code and call (require "delivery") then generate the template.

For bugs in delivered LispWorks images, the best approach is to start with a very simple call to deliver, at level 0 and with the minimum of delivery keywords (:interface :capi and :multiprocessing t at most). Then deliver at increasingly severe levels. Add delivery keywords to address specific problems you find (see the LispWorks Delivery User Guide .for details. However, please note that you are not expected to need to add more than 6 or so delivery keywords: do contact us if you are adding more than this.)

14.10.8 Send the bug report

Email is usually the best way. Send your report to

When we receive a bug report, we will send an automated acknowledgment, and the bug will be entered into the LispWorks bug management system. The automated reply has a subject line containing for example

(Lisp Support Call #12345)

Please be sure to include that cookie in the subject line of all subsequent messages concerning your report, to allow Lisp Support to track it.

If you cannot use email, please either:

Note: It is very important that you include a stack backtrace in your bug report wherever applicable. See Generate a bug report template for details. You can always get a backtrace from within the debugger by entering :bb at the debugger prompt

14.10.9 Sending large files

Note: Please check with Lisp Support in advance if you are intending to send very large (> 2MB) files via email.

14.10.10 Information for Personal Edition users

We appreciate feedback from users of LispWorks Personal Edition, and often we are able to provide advice or workarounds if you run into problems. However please bear in mind that this free product is unsupported. For informal advice and tips, try joining the LispWorks users mailing list. Details are at .

LispWorks Release Notes and Installation Guide - 2 Mar 2015