General Troubleshooting

Running Iguana from the command line

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.

Leave A Comment?

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