Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:This document provides guidance for resolving common issues encountered while using the WhatsApp Chat Analytics tool. It covers both the backend decryption script (chatsExporter) and the frontend web application (web). The primary sources of problems are typically incorrect configuration, missing dependencies, or invalid input files.
The process is divided into two main stages: unlocking the encrypted backup with the Python script and analyzing the resulting database in the web application. Each stage has its own set of potential issues and solutions outlined below.
chatsExporter - Decryption Script
This section addresses problems that may occur when running the whatsapp_db_android_exporter.py script to decrypt .crypt15 backup files.
Configuration Errors
Incorrect configuration in the .env file is a frequent cause of failure. The script requires specific variables to be set correctly.
Sources: chatsExporter/whatsapp_db_android_exporter.py:86-88, README.md:46-50
| Variable | Description | Common Issues |
|---|---|---|
ENCRYPTION_KEY | Your 64-character WhatsApp backup encryption key. | Missing key, key is not exactly 64 hexadecimal characters (after removing separators). |
TARGET_DIR | The folder path where your .crypt15 backup files are located. | The directory does not exist or is specified incorrectly. |
The script validates the ENCRYPTION_KEY by trimming any non-hex characters and checking if the resulting length is exactly 64.
Sources: chatsExporter/whatsapp_db_android_exporter.py:48-53
Dependency and Execution Failures
The script depends on an external tool, wa-crypt-tools, which is installed automatically via pip. Failures can occur during this installation or during the subsequent decryption steps.
The following diagram illustrates the execution flow and points of failure.
This diagram shows the step-by-step process of the whatsapp_db_android_exporter.py script, including validation checks and where specific exit codes are triggered.
Sources: chatsExporter/whatsapp_db_android_exporter.py:84-149
Script Exit Codes
If the script exits with a non-zero code, it indicates a specific error. Refer to the table below to diagnose the problem.
| Exit Code | Meaning | Troubleshooting Steps |
|---|---|---|
2 | Configuration Error | Check that .env exists, ENCRYPTION_KEY is present and valid (64 hex characters), and TARGET_DIR points to a real directory. |
3 | No .crypt15 files found | Ensure your .crypt15 backup files are in the specified TARGET_DIR. |
4 | wa-crypt-tools installation failed | Check your Python/pip installation and internet connection. Ensure git is installed. Try running with FORCE_INSTALL = True. |
5 | Key file creation failed (wacreatekey) | The ENCRYPTION_KEY might be incorrect, even if it passes the format validation. Double-check the key. |
6 | Decryption failed (wadecrypt) | The .key file may not correspond to the .crypt15 files. This usually means the ENCRYPTION_KEY is wrong. |
Sources: chatsExporter/whatsapp_db_android_exporter.py:89, 95, 110, 124, 134, 140
web/ - Web Application
This section covers issues related to the React-based web interface used for searching and visualizing chat data.
Setup and Startup
Before starting, ensure all dependencies are installed using npm install. The application is started with npm start.
Sources: README.md:81-83, web/package.json:10-25
A common startup issue can be related to webpack configuration. The project uses react-app-rewired to override the default webpack config, for example, to provide fallbacks for Node.js core modules that are no longer included in modern frontend tooling. If you see errors related to modules like crypto, stream, or buffer, ensure your config-overrides.js is correctly set up.
UI Step-by-Step Flow
The main analysis page (SearchSQLite) is a three-step process. Problems often arise from not completing a step correctly before moving to the next.
- Upload: User must upload
msgstore.dbandmodel-storage-chat.json. - Search: User configures filters (date range, chat, media type).
- Results: The application displays the filtered messages and analytics.
Sources: web/src/Pages/SearchSQLite/index.jsx:11, 55-68
The following diagram shows the user flow and interactions between components.
This sequence illustrates the flow from uploading files to viewing results, highlighting the validation check and the role of the useMessageSearch hook.
Sources: web/src/Pages/SearchSQLite/index.jsx:49-68, web/src/Pages/SearchSQLite/hooks/useMessageSearch.js:23-53, web/src/Pages/SearchSQLite/components/UploadStep.jsx
Common UI Problems
-
"Next" button is disabled on Upload step: This happens because one or both of the required files (
msgstore.db,model-storage-chat.json) have not been uploaded. ThecanProceedvariable controls this behavior.
Sources: web/src/Pages/SearchSQLite/index.jsx:119 -
Date range picker is disabled or shows "not loaded": The date range is loaded from the database after the
msgstore.dbfile is processed and the user navigates from the Upload to the Search step. If this fails, go back to the Upload step and re-upload the files.
Sources: web/src/Pages/SearchSQLite/components/SearchStep.jsx:38-42, web/src/Pages/SearchSQLite/hooks/useMessageSearch.js:23-32 -
Search fails or returns no results:
- The SQL query might be too restrictive. Try broadening the date range or clearing filters.
- An error may have occurred while executing the query. Check the browser's developer console for errors logged by
executeSearch. - The
buildMessagesQueryfunction constructs the SQL. An issue here could lead to invalid queries.
Sources: web/src/Pages/SearchSQLite/hooks/useMessageSearch.js:45-48, web/src/Pages/SearchSQLite/utils/queryBuilder.js.
-
Charts or statistics are not displayed: This indicates that the
MessageDataProcessorfailed to process the message list from the search results, or the list was empty. TheResultsStepcomponent will show "Loading messages..." if the search is in progress, but if it completes with no data, the charts will not render correctly.
Sources: web/src/Pages/SearchSQLite/components/ResultsStep.jsx:12-16