General Troubleshooting

Emergency code editing

General Troubleshooting: Iguana checks out the code that it is working on from Git into a local “sandbox” directory (<Iguana-install-directory>/edit/<user name>/). In an emergency you can edit this code directly. For example if Iguana is crashing when you open a script, then you could edit it manually to resolve the issue.

Running Iguana from the command line [top]

If you in a situation where Iguana is crashing then one helpful trick is to start Iguana as a command line process. You’ll need to go to the directory where Iguana is installed and run the Iguana executable (iguana.exe) at the command line. If Iguana is crashing on startup you can run Iguana in safe mode, which prevents any channels from auto-starting.

When you run Iguana from the command line it outputs various information, including: Configuration file issues, database issues, port conflicts, etc.

This allows you to diagnose issues such as:

  • Incompatible versions of Chameleon, you should be using the version of Chameleon (or higher) that’s shipped with Iguana.
  • Port conflicts, you may have applications on your system that are already listening on ports that Iguana wants to use.
  • Other issue that may cause problems with running Iguana as a service/daemon

Note: When running Iguana from the command line it uses the current user permissions, not the permissions for admin or localsystem (or the service/daemon user).

If any of your code needs special access you will need to logon as a user with sufficient permissions, for example: The service/daemon user.


  1. cd C:\Program Files\iNTERFACEWARE
  2. iguana --run
  3. iguana --run --safe_mode (optionally add safe mode to prevent channels starting)
  4. Use Ctrl+c to stop the server


  1. cd /Applications/iNTERFACEWARE-Iguana/
  2. ./iguana --run
  3. ./iguana --run --safe_mode (optionally add safe mode to prevent channels starting)
  4. Use cmd+c to stop the server

Note: If necessary substitute your own install directory above (step 1).

More Information

See deployment FAQs for more detailed information. Particularly: “How to run Iguana from the command line” for detailed command line output.

Delete corrupt index files [top]

One problem that can occur is if the index files for the logs have been corrupted. You might see a SQLite error referencing a malformed database image.

This can solved easily without loss of data:

  1. Stop the Iguana Service or Daemon.
  2. Go to the directory Iguana has configured to store its logs.
  3. Delete the contents of the subdirectory “index” – this contains the SQLlite index files.
  4. Optionally delete the contents of the subdirectory “meta” – this is another type of index stored in XML format.
  5. Restart the Iguana Service or Daemon.

The data for the logs is stored in the files with a *.log. Iguana will rebuild the index files from these core log files if the index files are deleted.

Diagnostic and debug pages [top]

You can use these URLs to run Iguana’s Thread Debug and Socket Diagnostic commands.

Thread Debug Info

This page lists the Iguana internal process threads.

Type in the following URL “<server name & port number>/thread_debug_info.html”

Screen Shot 2014-05-27 at 12.40.57

Socket Diagnostic

This page lists the Iguana web and LLP socket usage.

Type in the following URL “<server name & port number>/socket_diagnostic.html”

Screen Shot 2014-05-27 at 12.48.50

Leave A Comment?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.