Troubleshooting

Bruno Ferreira edited this page Feb 16, 2017 · 3 revisions

This page describes well-known problems and their solutions.

Details about the errors are not shown on the command line and are instead written to the log file, named dbptk-app.log.txt (located in the same folder as the DBPTK jar file). Please open the log file and locate the detailed error messages, as those details may be essential to find a solution on this page.

Other issues can be found / reported at https://github.com/keeps/db-preservation-toolkit/issues.


Getting exception "java.net.ConnectException: Connection refused"

Most databases are not configured by default to allow TCP/IP connections. Check your database configuration if it accepts TCP/IP connection and if your IP address is allowed to connect. Also, ensure that the user has permissions to access the database from your IP address.


Got error "java.lang.OutOfMemoryError: Java heap space"

The toolkit might need more memory than it is available by default (normally 64MB). To increase the available memory use the -Xmx option. For example, the following command will increase the heap size to 3 GB.

$ java -Xmx3g -jar dbptk-app-x.y.z.jar ...

The toolkit needs enough memory to put the table structure definition in memory (not the data) and to load each data row or row set, which might include having some BLOBs completely in memory, but this depends on the database driver implementation.


Main hard drive gets full due to temporary files

Due to the structure of some export modules (e.g. SIARD) and because we only want to pass throught the database once with minimum amount of used memory, all BLOBs and CLOBs of a database table must be kept on temporary files during the export of a table. This can cause your main disk to get full and the execution to fail. To select a diferent folder for the temporary files, e.g. on a bigger hard drive, use the option -Djava.io.tmpdir=/path/to/tmpdir. For example, the following command will use the folder /media/BIGHD/tmp as the temporary folder:

$ java -Djava.io.tmpdir=/media/BIGHD/tmp -jar dbptk-app-x.y.z.jar ...

Warning: The database reported a total of X rows. Some data may have been lost.

This warning means that there were some rows that were not processed. And should be accompanied by the number of rows that were actually processed.

Example with 34 out of 39 rows processed (5 rows are missing).

      Getting contents from table 'public.files'
WARN  The database reported a total of 39 rows. Some data may have been lost.
      Total of 34 row(s) processed
      Finished processing table 'public.files'

This might be caused by large LOBs in the database. In that case, an additional option may help DBPTK to process all the rows. For example, the following command will attempt to process a maximum of 1 row at a time (slower, but safer):

$ java -Ddbptk.jdbc.fetchsize.default=1 -jar dbptk-app-x.y.z.jar ...

Also consider providing more memory to the application.

This may also indicate that the database is corrupted, in which case the DBPTK may not able to read some of the rows unless the database is fixed.


Problems importing from Microsoft Access

In order to extract DB structures we need to have access to the internal database table Msysrelationships. You need to perform some hacking over the DBMS and this is version dependent. Please follow the instructions described on Microsoft's white paper, which explains how to do this for all Microsoft Access versions: "Preparing a Microsoft Access Database for Migration".

Log message: net.ucanaccess.jdbc.UcanaccessSQLException: UCAExc:::4.0.1 Decoding not supported. Please choose a CodecProvider which supports reading the current database encoding.

This happens when the MS Access database is password protected, but no password was provided. Information on how to provide the password in the command line arguments may be found in the Application Usage page.

Log message: net.ucanaccess.jdbc.UcanaccessSQLException: UCAExc:::4.0.1 Incorrect password provided

This happens when the password provided via command line was incorrect. You can try to provide the password between " " to avoid problems related to using characters with special meaning in the command line (note that if you do this and your password includes the character ", you need to enter it as \").