Users Guide 2.x - Troubleshooting

From PDS Software Solutions LLC
Jump to: navigation, search


Installation and Initialization

Part 1 - Installation and Initialization

Creating, Viewing and Editing Notes

Part 2 - Creating, Viewing and Editing Notes

Encrypting and Decrypting Files and Directories

Part 3 - Encrypting and Decrypting Files and Directories

Customizing the PDS Application

Part 4 - Customizing the PDS Application

Verification, Configuration and Other Tasks

Part 5 - Verification, Configuration and Other Tasks

Troubleshooting PDS

Unable to Open (or decrypt) a Note or File

While PDS attempts to provide useful messages to help you overcome any roadblocks you may hit, a secure application should not be very helpful to anyone who is attempting to use the application to break the security (in this case, the encryption) of the application. For that reason, if you are unable to decrypt your data you should not expect PDS to do everything possible to help you resolve the problem.

PDS has been tested under many different scenarios, and those that have been deemed to be helpful (like unable to read the file, and even providing the wrong credentials) display a minimally helpful dialog.

The best prevention against not being able to access your information is fairly simple. First, make backups of your encrypted data, and verify that those backups are valid; PDS is able to perform the validation. The next step is to make backups of your KeyStore(s) - not just one copy of your each KeyStore, but two.

Another tip is in the naming of the KeyStore. You may be tempted to create a KeyStore by reusing the name of a previously created KeyStore, as the new KeyStore will reside in a different directory. Please resist that temptation. While not fatal, it may cause problems for the code that uses the KeyStore Search Path, as there is no accounting for multiple KeyStores with the same name. PDS uses the KeyStore Search Path when the KeyStore, as indicated within the metadata of the PDS file, is not found in that location.

Unable to Open (or decrypt) a Note or File created on another computer

The most common cause for this error is that PDS is unable to initialize the cipher on the computer having the error. This is always seen when the file is created using an AES-192 or AES-256 cipher and the computer exhibiting the error does not have the "Unlimited Strength" Java Cryptographic Extension (JCE) bits.

As there is no way to change the encryption of the file, is is necessary to change the JCE from Strong to Unlimited so that a cipher capable of supporting these larger key sizes can be created. Well, that or re-encrypting the information without using an Unlimited Strength cipher.

Note that upgrading the JCE in your JRE is just a matter of swapping out a couple policy files that you can download from Oracle. But with a fast download rate it may be faster just to download and install the latest JDK from OpenJDK.

PDS will not start

Is there an error dialog like the one below, but with a different error message? If so, please see the section entitled "Functionality X did not successfully complete" below.

Has the application been working fine, but today it won't start? If so, what's changed? If nothing, what's happened since it was working (a bad shutdown or a new software update)? Answers to these questions often lead to the solution.

If still unsolved, a quick check of the applications' state is in order. The way to do this is:

1. Locate the state file (typically $HOME/.pdsState) associated with the PDS instance that will not start. See "Installation and Initialization" in this Users Guide to locate the file.

2. Do not delete the file, but instead, rename it.

3. Try again to start PDS.

If this does not resolve the problem, it is possible that the PDS executable has become corrupted. You could try downloading a new copy of PDS and see if that resolves the problem.

If none of the suggestions thus far resolve the problem, the next best attempt is to try starting the application from the Command Line Interface (CLI). The CLI, and the output to the terminal, are your friends. PDS displays dialogs when things go wrong, but there is additional detail sent to standard error (typically the controlling terminal). This information, along with anything from the Operating System, should be very helpful for a Google search, or for contacting the PDS team. To start PDS from the command line you can simply type in:

java -jar /path/to/pds.jar

or, you can use one of the startup scripts distributed with the releases. These scripts are (Linux) and pds-start.bat (Windows). If you have a Mac release of PDS, you'll need to look inside the application directory ( and find the startup script (and README) in the Plus directory.

Note that when running from the CLI or script, pressing the CTRL-C key combination in the CLI will KILL the application immediately. It will *not* do a graceful shutdown, prompting you about any unsaved modifications in your PDS Notes, as is done when closing PDS via the GUI.

Windows reports a Permissions problem

Scenario: You are able to successfully use PDS on a USB drive with Linux or Mac, but it will not start on Windows.

In this scenario, there is an error dialog (Figure 1) with a "helpful" message.

The root cause is that Windows seems to treat "dot files" (files that begin with a period, or dot) different than others. On some versions of Windows, you may resolve the issue using the following steps:

1. Open Control Panel and select Folder Options. Under Files and Folders, and Hidden files and folder, check the Checkbox to "Show hidden files and folders." This will allow you to see the file listed in Windows Explorer.

2. Navigate to the root directory of Find the file ".pdsState" and right click the file to bring up a menu. On the menu, select "Properties", uncheck "Hidden", and keep "Read-only" unchecked. Then click OK.

3. Restart PDS.

Fig 1. Access denied on Windows

Functionality X did not successfully complete

PDS does its best to display a meaningful error dialog when something goes wrong. Often times the problem is that meaningful to one person is not "meaningful" to another. If you do see an error message that is not meaningful to you, please know that you are probably not alone - let the team know.

Given the wide range of Operating Systems (and versions of each Operating System) that PDS is able to run on, there may be significant enough differences between versions that do cause problems. Naturally, the first thing to do is to retry the action that caused the error and see if it is reproducible. If it is, that's actually a good thing (well, to some of us it is).

If the problem is reproducible, and the error message is not helping you resolve the problem, please start the application from an appropriate startup script provided within the release, or manually from the Command Line Interface ($ java -jar /path/to/pds.jar). This will allow you to capture any standard output/error and also identify exactly when the output was generated. If you do find something to report, please send that information to the PDS team.

At this point in PDS development, the Command Line Interface is the recommended method for the public to troubleshoot PDS. For Mac users, Internet reports are that Java's standard out and standard error messages showed up on the Mac console through 10.7, but that as of 10.8 these messages are filtered and are no longer seen. This means that Mac users needing to get more information will need to use a startup script, which will not display PDS in the Mac look and feel but instead in the Metal look and feel.

Finally, know that a secure application should not divulge too much information when problems occur, so the amount of information provided within public releases of PDS may not be sufficient for anything more than verifying a bug and reporting it. If you do reach that point, please contact the PDS team at

(C) PDS Software Solutions LLC, 2009-2017 - All rights reserved.
By using this website, you signify that you agree to be bound by the express terms of use.
We value your privacy.
Personal tools