There are only a few failure modes of the Firefly server, and the following procedures outline the troubleshooting steps that will help isolate and correct those problems.

Can't See Server

One common problem is that you can't see the firefly server after you install and start it. There are two or three obvious first checks:

1. Check that the server actually started. On Windows, check the tray applet to see if it is running. On Mac, check the preference pane. On linux or other Unixes, check your process list:

   foo@bar:~$ ps auxw | grep -i "mt-daap[d]"
   

2. Make sure your iTunes or other client is actually looking for the device. In iTunes, make sure the "Look for shared music" checkbox is checked in the "Sharing" tab of preferences. With Rhythmbox or Banshee or some other client, make sure you have the DAAP module installed and loaded.

3. Make sure you have multicast enabled. Some wireless routers require that you enable multicast (sometimes also labeled "IGMP") in the web administration interface of the router. Others require firmware updates to enable multicast. Try updating your router to the latest version. As a testing point, if it works fine when the server and client are both on the wired side of the router, but it doesn't work when one side is wired and the other side is wireless, then that points to the router as the culprit.
4. Check your firewall. The server is found using Apple's Bonjour protocol. If you have a firewall, try disabling it and seeing if that works. If it does, then it points to the firewall as a problem. You can open a smaller hole by just allowing traffic to and from 224.0.0.251 on port 5353 UDP.
5. On unix, check that you don't have multiple mDNS daemons running. Sometimes, multiple mDNS responders, like the one built in to Firefly conflict with the ones you may already have installed (Apple's implmentation, Howl, or Avahi). If you already have an mDNS responder, start mt-daapd with the "-m" argument to disable the internal mDNS daemon and edit the configuration for your existing mDNS daemon to advertise _daap._tcp on 3689 (or whatever port you are using) and _rsp._tcp on the same port. For Howl, the /etc/mDNSResponder.conf would look something like this:

   #       name                    type            domain  port    text record
           "Music Server"     _daap._tcp      local.  3689
           "Music Server"     _rsp._tcp       local.  3689
   

6. On Windows, it might be worth re-installing a new version of Apple's Bonjour for Windows. This is also the solution if you are running Gizmo, which seems to somehow pooch Bonjour.

7. Check your VPN client. When active VPN clients can close down the ports required for communication with Firefly.
8. On Windows, check your anti-virus settings. Some anti-virus products have a feature known as 'worm protection' that acts as a firewall. You may need to disable this or allow Firefly in the exceptions list.

Server Keeps Stopping (Crashing)

1. Look at your logs. Usually they will tell you something informative about why the server had to stop. For example, it may tell you that your permissions on the database are too restrictive, or that it can't find the config file. Something of that nature. On Windows, check your event log for errors. On Unix, check your syslog.
2. If it crashes while scanning, then there is probably a file that is choking it. You'll know this is the problem when you see logs that looks like this:

   2007-01-31 07:57:56 (93f86028): Full reload...
   2007-01-31 07:57:56 (93f86028): Starting mp3 scan
   

   • If you see these messages, but never a message like this:

   2007-01-31 07:57:57 (93f86028): Scanned 20 songs in 1 seconds
   

   then it is likely crashing while trying to retrieve metadata from one of the songs. You can find out which by running it in a higher debug level, and seeing what the last file it scanned was. In Windows, you can run the "Debug Mode" server (Start -> Programs -> Firefly Media Server), then look at the log through the "Log" tab on the tray applet. Scrolling from the bottom, you'll see the last file it tried to index before the scanning stopped. Move that file out of the way, and it should scan normally. On Mac and Unix, you will need to add a "logfile" to the config file, and set the "loglevel" to at least 5 to be able to see the same level of log detail.

Server Won't Start

1. Look at your logs. Usually they will tell you something informative. On Windows, check your event log for errors. On Unix, check your syslog. One common cause of start up failures is that Firefly can't read the music directory. If this is the problem you should see something in the logs like the following:

   Apr 3 18:52:07 mt-daapd[575]: Error scanning MP3 files: Permission denied
   

   There are two common causes of this issue. First check that the mp3_dir entry in the mt-daapd config file is pointing to a valid directory. If not, then edit the config file as appropriate. Note that you'll need to do this via the command line as Firefly isn't running. Second, check that the permissions of the mp3_dir directory (and the files it contains) allow read access. On Unix Firefly runs as nobody (guest on nslu2) so make sure that those users have sufficient read priviliges.