Back to Guide Home


This part of the guide will discuss troubleshooting synchronization, as that is by far the most complex feature of the application. There are three major parts to this section, General Tips, Troubleshooting Wi-Fi Sync and Troubleshooting Dropbox Sync.

General Tips


The first thing to check is what version of the Android app and what version of the Moneydance extension you are running. These are the current version numbers that are tested to work properly together:

To check the version on your device, run HandyBank and press Menu, then go to Settings → About.

To check the version in Moneydance, select Extensions → Manage Extensions... from the Moneydance menu and scroll down the list to HandyBank Synchronizer. In Moneydance 2010, select Extensions → Get Info For → HandyBank Synchronizer.

Full Shutdown Sequence

Sometimes it can be difficult to get your mobile device to initially appear in the list of devices that can be added in the HandyBank extension. Also, there can be troubles getting the system to sync correctly when you are switching from Wi-Fi sync mode to Dropbox sync mode, or the other way around. It can be helpful in these situations to get the system to a known good state. Follow this sequence to get the system to shut down completely and start back up:

  1. In HandyBank on your mobile device, make sure you have Enable Dropbox synchronization turned on or off as desired in the Settings window.
  2. Close HandyBank on your device (Menu → Quit).
  3. Go to App settings on your mobile device (something like Menu → Settings → Applications → Manage applications → HandyBank) and press Force Stop.
  4. In Moneydance on your desktop or laptop, go to Extensions → Configure HandyBank... and ensure the synchronization method that matches what you chose in step 1 above is selected.
  5. Save and close Moneydance.

(at this point both applications are configured for the same type of sync (Wi-Fi or Dropbox) and are not running)

  1. Run Moneydance.
  2. Go to Extensions → Configure HandyBank...
  3. Run HandyBank on your device. Go to Menu → Settings → Show Access Code.
  4. Wait 20 seconds.
  5. In Configure HandyBank.. on your desktop or notebook, click Add Device.
  6. If you get the "No devices found" message, click close and wait 20 seconds again. Click Add Device.

The full shutdown and restart sequence above helps make sure all the settings are both correct and being used by the software, as well as help ensure there is enough time for the system to start up. If you still cannot connect with your device after following this sequence, you should go to either the Troubleshooting Wi-Fi Sync or the Troubleshooting Dropbox Sync section.


Both the HandyBank app on your Android device and the HandyBank extension for Moneydance will record information in a log to help you figure out what might be going wrong. In the Android app, the log is seen by clicking on the Last Sync text on the Main Screen.

Go To Sync Log

The synchronization log contains the last 100 log entries, which may contain status messages, error messages, or other information that can help you decide what the problem could be.

Synchronization Log

The log on the Moneydance side can be found by selecting Help → Console Window. All messages in the Moneydance log that come from the HandyBank extension will start with the word "handybank: ".

There are over 25 different messages for Wi-Fi sync and over 40 messages for Dropbox sync, and some of those messages can have multiple different system messages reported with them. Instead of detailing each message, this page will explain how sync works for Wi-Fi and Dropbox. Armed with that information and the messages in the logs, you will hopefully have enough information to know how to solve the problem.

If you read the log messages and the appropriate section on Wi-Fi or Dropbox and you're still having troubles on the device, there are two more steps you can take.

Step 1 - Less Drastic

The HandyBank Android app is designed with a background service that handles data synchronization. This service is always running. Sometimes it is helpful to shut it down and restart it. To do this, you need to go to Application Settings for your device. Each device is different, so instructions on how to get there are beyond the scope of this document. For the original Motorola Droid, the pathway is Settings → Applications → Manage applications → HandyBank

Application Settings

To shut down the service, click the Force Stop button. If the button is disabled, it means the service has already been shut down.

Step 2 - More Drastic

As a measure of last resort, you can clear all the data off your device and start over from the beginning. HandyBank will actually do this for you if you enable PIN access and then enter in an incorrect PIN too many times. To clear the data manually, go to Application Settings as described above and click Clear Data. You should be prompted with an "are you sure?" type of dialog. Upon clearing the data, any transactions you've entered on the device that have not been successfully synchronized with the desktop Moneydance will be lost, and you'll need to re-enter them.

If your data has been cleared, you will need to go to Moneydance and select Extensions → Configure HandyBank... and select the device name you were using. Click Forget Device and then click OK to remove the old (and now unusable) device configuration. After this, follow the setup instructions to set up HandyBank.

Wi-Fi Synchronization

Wi-Fi Design

Wi-Fi sync requires that both HandyBank on the mobile device and Moneydance on the desktop are running at the same time, and with the device and the desktop connected to the same network. With both applications running, a "handshake" sequence occurs to synchronize data. This handshake goes something like this:

  1. Device announces "I am here!" using the Apple Bonjour system of network device discovery
  2. Desktop sees the announcement and sends a test message encrypted with the Access Code you entered during setup
  3. Device decrypts the test message and responds back with decrypt success or failure
  4. If the desktop receives a decrypt failure, it shows an error message (and logs the error) and the process stops
  5. If decrypt success is received, all subsequent transmissions are encrypted with AES
  6. Device transmits any transactions that were entered into the device since the last sync
  7. Desktop processes received transactions and enters them into the Moneydance file
  8. Desktop recomputes budget information and transmits the currency, account, transaction, settings and budget information needed by the device. It only transmits the number of days of transactions that is set in HandyBank extension settings, it does not send the entire file. Only limited information is transmitted -- for example account numbers are not transmitted with the accounts
  9. Device receives and processes the now-updated information
  10. If the information passes consistency checks (to make sure nothing was lost during transmission), the list of transactions entered on the device since the last sync is deleted

In addition to listening for "I am here!" messages, the HandyBank extension on the desktop will also scan for any existing devices a few seconds after starting up Moneydance or opening a file. If you leave Moneydance running, however, you may not receive any messages that initiate Wi-Fi sync. This is where the Request Sync feature comes into play. If you click Request Sync from the Main Screen with Wi-Fi sync enabled, the following sequence occurs:

  1. Device shuts down the Apple Bonjour connection.
  2. The Bonjour system transmits a "Goodbye." message
  3. Desktop receives the "Goodbye" message and removes the device from a list of actively connected devices
  4. Device waits 2 seconds, required by the software that implements the Bonjour connection
  5. Device starts up a new connection with Bonjour
  6. Bonjour transmits a "I am here!" message
  7. Desktop receives the message and sync progresses as described above

Note that one of the assumptions of Wi-Fi sync (currently) is that you have only one Moneydance file involved. If you have two files, for example file A for your personal finances and file B for business finances, you should only add your device to one of the files. Otherwise, the system will try to sync with both of them. This means if you enter transactions on the device that are meant for file A, but sync is initiated for file B, the file A transactions will be incorrectly entered into file B. The best way to avoid this problem is to only add your device to one file using Extensions → Configure HandyBank.

HandyBank is designed to run as a background service on your Android device, so it is always running unless you select Quit from a menu or Force Stop it from Android Manage Applications.

Wi-Fi Troubleshooting

These are some of the reasons why Wi-Fi may not work correctly:

Dropbox Synchronization

Dropbox Design

Dropbox sync has some advantages compared with Wi-Fi sync. It does not require that both HandyBank on the mobile device and Moneydance on the desktop are running at the same time, and it can function over 3G so a Wi-Fi connection is not mandatory. Additionally, Dropbox sync is better suited for multiple devices.

Warning: Do not use the shared folders feature of Dropbox to store your HandyBank sync files with multiple devices. Instead, simply log in to the same Dropbox account on each device, on this screen. Logging in to a Dropbox account here will have no effect on which Dropbox account is used for other apps on your device.

Using the shared folders feature in Dropbox is not a tested scenario, and may result in data loss.

Because there is no "live" connection like there is for Wi-Fi, there is no "handshake" that happens all at once. The sequence of events for Dropbox sync is something like this:

  1. Device says "Here are transactions the user entered on-the-go". It also sends the time of transmission.
  2. (Time passes, more transactions can be entered on the device)
  3. Desktop reads transactions from step 1 (from all registered devices) and stores the time of transmission.
  4. Desktop combines mobile device transactions from step 1 and says "Here's the new data", as well as last time of transmission of transactions received.
  5. Device reads new data file and the time of transmission.
  6. Device removes transactions that happened at or before the time of transmission (e.g. the transactions from step 1).
  7. Device transmits transactions from step 2, since they came after the last transmission time processed by the desktop.

HandyBank is designed to run as a background service on your Android device, so it is always running unless you select Quit from a menu, user Force Stop from Android Manage Applications, or your Android device automatically shuts down the HandyBank service. If the service is running, HandyBank will periodically check Dropbox for new information to sync with. When you use Request Sync, the interval shortens as new data could be available if Moneydance performs a sync.

Dropbox Folder and Files

If you are not directly linking to the Dropbox cloud, HandyBank needs to use a special folder structure within your Dropbox files in order to allow both the mobile device and the extension in Moneydance to be able to talk to each other. The primary cause of problems with Dropbox sync is not setting the correct folder in the Configure HandyBank... window.

Suppose your user name is Frank and you're using Windows 7, and you've named your Android phone "Frank's Droid". Your Dropbox folder structure might be something like this:

A  Users\
B    Frank\
C      Documents\
D*       Dropbox\
E          .moneydancesync\
F            Frank's Droid\

The correct folder to pick in the Configure HandyBank window is D. Folders E and F are added automatically by either the HandyBank app or the HandyBank extension. If you pick C, E or F, the extension will automatically select D for you. However, if you pick folder A, B, or any other folder on your system, the system won't be able to synchronize.

One quick way to properly find folder D is to right click on the Dropbox icon in the system area of your desktop. A context menu should appear, and one of the times on the menu should be Open Dropbox Folder. This should open a view of folder D indicated above, and you should be able to copy and paste the path into the Configure HandyBank window.

Note that your Moneydance file (ending with .md) can be anywhere on your system, it does not need to be in Dropbox. HandyBank does not open or read your Moneydance file. To synchronize, HandyBank uses 4 files below the .monedancesync/{Device Name}/ folder. You don't need to mess with these files. Deleting them will likely cause you to lose data, but you can delete them safely after you have used Forget Device in the HandyBank extension settings. Just for your information, these are the files:

Dropbox Troubleshooting

These are some of the reasons why Dropbox may not work correctly:

Back to Guide Home