View source for Troubleshooting Zimbra Desktop FAQ

==When Things Go Wrong==

====At the end of installation, I see Zimlets injection failure and the UI window says it can't connect to the server.  What's wrong?====
:This means that the back end server can't be reached on localhost port 7633.  The same error however have many different causes:
:*The server didn't start up. - Check if the back end process is running.  On Windows the process is zdesktop.exe, and on Mac/Linux it's a java process.  If the back end server is not running, check <install>/log/zdesktop.out and <install>/log/zdesktop.log for errors.
:*The server can't bind to port 7633. - Maybe the port is taken by a different application, but this is rare.
:*A system firewall blocks access to localhost port 7633. - Such firewalls are more popular on Windows than on other platforms.  If you are using a Windows firewall, check its settings.
:*System is misconfigured and localhost can't be resolved. - Many Mac OS computers have this issue.  If you are on Mac OS, try the following steps:
::#Make sure localhost is resolved to 127.0.0.1 on this computer.
::#Make sure your computer has a name.  You can set that under System Preferences -> Sharing.  Also make sure computers on your network can access your computer at <computername>.local.
::#If it still fails, the last resort is to change the binding of the back end server from localhost (loopback) interface to all interfaces.  Open the config file <install>/jetty/etc/jetty.xml with a text editor and remove the line <Set name="host">localhost</Set>.  Save the file and then restart the back end server.

====My emails stopped coming in.  What's wrong?====
:It could be that synchronization with remote server encountered an error.  Some errors are recoverable, like when the remote server is temporarily unavailable or your network connectivity is down.  First look at the sync indicator on the title bar above the folder tree on the left.  When things are working, there should be a green dot indicating the mailbox is online and well.  If you see a red square, you are having connectivity issue with the server which is typically temporary.  When the indicator is a red dot with an exclamation point, an error has been encountered during sync.  Mouse over the red dot to see a tooltip with more information.

====What do I do when I'm blocked by an error?====
:If your sync cycle always ends in error with the red dot indicator, you may have found a bug in the software.  To help us debug the issue, first collect some debug information.  In the mailbox search box on the top left (not the web search box on the right), type in "$set:debugtrace on" (without the quotes) and hit enter/return.  You'll see a green popup saying debug trace is turned on.  Then click the Send/Receive button to manually force a sync and wait for the spinning indicator to turn into the red error indicator.  Then open the log file <install>/log/zdesktop.log and find the trace section of lines between
    ============================== SYNC DEBUG TRACE START ==============================
:and
    ============================== SYNC DEBUG TRACE END ================================
:If you have multiple such sections, find the last trace section.  Then post the issue to the [http://www.zimbra.com/forums/zimbra-desktop ZD Forum] with the trace.  If the trace is too long, put it in a file and attach to the post.  Alternatively you can also file a bug on [http://bugzilla.zimbra.com/enter_bug.cgi?product=ZCS Zimbra Bugzilla], choose Desktop Client as component, and attach the trace to the bug.  If the trace contains information you do not wish to make public, mark the bug as private so that only Zimbra employees can access it.

====I'm seeing some UI display issues.  How do I correct that?====
:It's often hard to tell between a UI display issue and a data issue.  However if you suspect there's something wrong with the display, you can try a few things to verify.  First, click on the folder in the left folder tree pane, this will cause a refresh and displays the content of that folder.  This applies to not only mail but also contacts, calendar and other data types.  Secondly, you can use the Shift+F5 shortcut to force a fresh of the UI, which is equivalent to closing and relaunching the UI window.  If the issue goes away after doing so, it's a display issue.

====The UI does not load at all, or some parts of the UI are left blank, what should I do?====
:First, check the log file located at <install>/log/zdesktop.log.  If the problem is caused by the back end service you will see some errors in the log.  Secondly, try using a Web browser to display the UI and see if you get the same behavior.  Firefox is the preferred choice because the UI display engine we use in ZD is based on Mozilla software.  To use Firefox or any other browsers to display ZD UI, you first need to find your personalized URL.  Open the file <install>/zdesktop.webapp/webapp.ini with a text editor and find the "uri" key, and the value after "uri=" is the URL to use with your browser.  The URL will look something like this:
    http://localhost:7633/desktop/login.jsp?at=7e58c54e-60f2-4d90-878f-b1d89d276d15

====When checking for errors in the log file, what do I look for?====
:An error often generates an exception stack which helps pinpoint where it was originated in the code.  An exception stack looks something like this:

    Code:service.FAILURE
            at com.zimbra.common.service.ServiceException.FAILURE(ServiceException.java:253)
            at com.zimbra.cs.datasource.ImapSync.connect(ImapSync.java:147)
            at com.zimbra.cs.datasource.ImapSync.importData(ImapSync.java:118)
            at com.zimbra.c s.datasource.DataSourceManager.importData(DataSourceManager.java:154)
            at com.zimbra.cs.mailbox.LocalMailbox.importData(LocalMailbox.java:327)
            at com.zimbra.cs.mailbox.LocalMailbox.syncAllLocalDataSources(LocalMailbox.java:300)
            at com.zimbra.cs.mailbox.LocalMailbox.sync(LocalMailbox.java:357)
            at com.zimbra.cs.mailbox.LocalMailbox.syncOnTimer(LocalMailbox.java:282)
            at com.zimbra.cs.mailbox.DesktopMailbox$1.run(DesktopMailbox.java:117)
            at java.util.TimerThread.mainLoop(Timer.java:512)
            at java.util.TimerThread.run(Timer.java:462)
    Caused by: com.zimbra.cs.mailclient.CommandFailedException: LOGIN failed: LOGIN failure. Server Error-Please try again after some time.
            at com.zimbra.cs.mailclient.imap.ImapRequest.checkStatus(ImapRequest.java:94)
            at com.zimbra.cs.mailclient.imap.ImapRequest.sendCheckStatus(ImapRequest.java:80)
            at com.zimbra.cs.mailclient.imap.ImapConnection.sendLogin(ImapConnection.java:118)
            at com.zimbra.cs.mailclient.MailConnection.login(MailConnection.java:205)
            at com.zimbra.cs.datasource.ImapSync.connect(ImapSync.java:143)
            ... 9 more

:When providing information on an error from log file, please include at least a few lines before and after the exception stack to be complete. 

====I see a popup error saying something is wrong when I try to perform a task.  What should I do?====
:You should check the log file located at <install>/log/zdesktop.log for possible errors near the end.  It will also be very helpful to get the soap debug trace between the UI front end and the back end service.  To collect the soap trace, you will need to use a Web browser like Firefox.  Make sure the browser allows popup windows.  You also need to find your personalized URL.  Open the file <install>/zdesktop.webapp/webapp.ini with a text editor and find the "uri" key, and the value after "uri=" is the URL, which will look something like this:
    http://localhost:7633/desktop/login.jsp?at=7e58c54e-60f2-4d90-878f-b1d89d276d15
:Now add an additional '&dev=1' parameter at the end of your personalized URL like this:
    http://localhost:7633/desktop/login.jsp?at=7e58c54e-60f2-4d90-878f-b1d89d276d15&dev=1
:When you navigate to this URL, the browser will pop up a soap trace window during loading of the UI.  Wait for the UI to be fully loaded, perform the same task you had trouble with, make sure the same popup error happens, and provide the entire content of the soap trace window.  Please note that the soap trace often contains private data so it's a good idea to file a "private" bug on [http://bugzilla.zimbra.com/enter_bug.cgi?product=ZCS Zimbra Bugzilla], choose Desktop Client as component, and attach the trace to the bug.  A bug marked "private" is only accessible by the reporter and Zimbra employees.

====What additional information can I collect to debug a UI display issue?====
:In the ZD UI window, use Shift+F6 to reveal the status bar on the bottom.  Click on the Settings icon at the right end of the status bar and select Tools -> Error Console.  Then click "Errors" on the top to filter out non-error information.  If there are any errors they will be helpful in debugging your issue.


{{Article Footer|N/A|12/31/2008}}

[[Category:FAQ]]
[[Category:Troubleshooting Zimbra Desktop]]