All documents in a DEVONthink database have a path the file system where their content file is located. This path is stored for every document, imported or indexed. If DEVONthink can't find a file at a path stored in its index, it will be reported as missing.

The most common cause of missing files is indexed files being moved in the Finder, or the indexed parent folder being renamed. In the first case, the file isn't in the location it was indexed from. Moving the file back into place will resolve this issue. In the second case, the path no longer exists as the names in the path have changed. Changing the name back will resolve this.

The second most common cause of missing files is people modifying the internal contents of a database. Some Finder replacement applications, like PathFinder, allow you to access package files like normal folders. The internals can also be accessed by other methods, like the command line or the Finder's contextual menu. If you delete or reorganize anything, you can easily cause missing files.

Dealing with missing files: Missing files are reported in DEVONthink's Window > Log. To deal with these files, Control-click the item in the Log window and choose one of two options:

Just as with any database application, controlling the data flow in and out is a critical process. DEVONthink should be the gatekeeper of the files in its databases. If an external agent, whether and application or a user, adds files outside DEVONthink, they will cause an internal inconsistency and lead to orphaned files when following the steps below.

The most common cause of orphaned files is a simple and common one: attempting to create revisions. Say you open a file, a Word document, in an external application. As you are reading it, you decide to make some changes. You type your edits, and select File > Save As (or File > Duplicate the file first). The application most commonly will open the Save dialog in the location of the original file, in this case, inside the internals of the database. You have just created an orphaned file DEVONthink knows nothing about. So the question becomes, how do I create a revision without causing this issue?

The other common cause is the same as with missing files: getting into the database package and adding files manually.

Another report you may see in the Log window is regarding file integrity. DEVONthink scans and stores a SHA1 checksum for each file in a database. This value is updated as the files change. However, if you use the utility command File > Check File Integrity, it may report an integrity error. This means the stored checksum doesn't match the newly scanned checksum. This may indicate a problem with the file itself. However, this error will also be reported for indexed items that are not up to date.

As a first step, use > File > Verify & Repair Database to check your database's consistency and allow DEVONthink to take all necessary steps to repair any discovered problems. This check will include reporting any missing files, as discussed above, and importing any orphaned files. If Verify & Repair Database was able to repair your database, use File > Optimize to optimize your database and have DEVONthink create an internal copy of the index.

If Verify & Repair was not successful or your problems are not resolved, proceed with the next step.

DEVONthink keeps up to two copies of the index files in case that the index is damaged beyond repair.

To restore the index file(s) from a previously saved internal backup, hold the ⌥ Option key and select File > Restore Backup. DEVONthink presents you with a list of all available backups. Choose the latest one and click Open. This swaps the current set of index files with the chosen backup metadata (the current set of index files becomes the backup, the backup becomes the current set) so that data is never overwritten. Run File > Verify & Repair to check the consistency of this index version and if everything is in the right order use File > Optimize to optimize your database and have DEVONthink create a fresh internal copy of the good index.

If the backed-up index files are also defective, try the other backups, if available. If all backups are broken or corrupted, proceed with the next step.

Since your files and DEVONthink's index are stored independently within the database package, the index can be rebuilt at any time without you losing metadata. However, we generally only suggest this when troubleshooting a database issue.

To rebuild the database from scratch, use File > Rebuild Database. During the rebuild process, the index is completely recreated. Your actual files are not touched. Any problems that occur during this process are logged. Also, a new backup metadata set will be created at the beginning of the rebuild.

If everything above failed, your database is severely damaged. You have basically two options:

Time Machine: Restore your database from your Time Machine backup or whichever backup medium you use. If you don't use Time Machine, we strongly advise you to do so. External hard disks are cheap, and Time Machine makes backing up your important files quick and simple.

Manual Rebuild: If you find yourself in the unfortunate situation where you have no backups, it may be possible to rebuild your database manually, following these steps:

If none of the above steps helped solving the problems you have with your database, please contact us with a precise-as-possible description of your problem.