Essential WhatsApp files are missing Troubleshoot in iOS

[ebulku]

What are some ways to troubleshoot the error: Essential WhatsApp files are missing from the iOS backup. Perhapse you enabled end-to-end encryption for the backup?

I have checked all the issues related to that error and there are two cases:
a. You have enabled e2e encryption inside WhatsApp Settings > Backup #125
b. You have a Business Account and you are not using the --business flag #164

I have successfully exportet the chats from my iOS 18.3 iPhone, but it is failing in another one with iOS 26.1. (logs in the end)

Since the backup of iPhone is more than 200GB, it is a bit hard to troubleshoot with different cases, so can somebody help with these questions:

1. Do you have to make at least one backup from WhatsApp Settings > Chat backup so Whatsapp-Chat-Exporter can work?
2. Do you have to enable/disable WhatsApp inside IPhone Settings > iCloud Backup, or that is not related at all with the backup you are doing it in your PC though iTunes

Encryption detected on the backup!
Enter the password for the backup:
Trying to decrypt the iOS backup...Done
Decrypting WhatsApp database...WARN: decrypted 543297536 bytes of '7c7fba66680ef796b916b067077cc246adacf01d', expected 714215424 bytes!
Essential WhatsApp files are missing from the iOS backup. Perhapse you enabled end-to-end encryption for the backup? See https://wts.knugi.dev/docs.html?dest=iose2e

[KnugiHK]

I have successfully exportet the chats from my iOS 18.3 iPhone, but it is failing in another one with iOS 26.1. (logs in the end)

If E2E encryption and the Business flag aren't the issue, this is likely a version-specific change in iOS. It's possible Apple has introduced a new mechanism to protect or store these files in your specific version. I cannot verify this currently as I don't have an iPhone running that version to perform the necessary analysis.

Do you have to make at least one backup from WhatsApp Settings > Chat backup so Whatsapp-Chat-Exporter can work?
Do you have to enable/disable WhatsApp inside IPhone Settings > iCloud Backup, or that is not related at all with the backup you are doing it in your PC though iTunes

No, the tool extracts data directly from the internal WhatsApp databases found in the iPhone backup. It does not rely on, or interact with, the 'Chat Backup' feature within the WhatsApp app itself.

[Jomolungma]

After experiencing the same issue, I did some digging, and I found that the root cause for the "Essential WhatsApp files are missing" error is a missing contacts database. After commenting out the extraction of the WhatsApp contacts file, ios_media_handler.py lines 111-115, WhatsApp Chat Exporter works well. Seems like the contact database is not that essential -- the branch for unencrypted backups does not mind either -- see lines 183-186.

I still get lots of warnings "decrypted bytes, expected bytes", but WhatsApp Chat Exporter proceeds nonetheless apparently without missing anything in the file contents.

[Jomolungma]

I have created bug 215 for this issue and proposed a PR to fix it. This change allows the exporter to continue when the contacts database is missing. However, I do not know if this is the best solution here. It could be that the name of the contacts database has changed.

When I export group chats as a ZIP file from within WhatsApp, I get sender names apparently taken from the phone's address book.

In the chats exported using WhatsApp-Chat-Exporter, I get random UUIDs instead of sender names. Is there any option to improve this?

[KnugiHK]

The proposed fix is merged to the dev branch. Closing...

[KnugiHK]

Please reopen this discussion if the issue persisted in the dev branch.

[Surfict]

Hello, I had this issue, the error in the dev branch disappeared, but another one appeared:

alexandre@Alexandres-MacBook-Air WhatsApp-Chat-Exporter % wtsexporter -i -b '/Users/alexandre/Desktop/Backup full iphone from finder/00008110-001644910ABB801E' \
  -j result.json --avoid-encoding-json --no-html
========================================================================================================
                  ██╗    ██╗██╗  ██╗ █████╗ ████████╗███████╗ █████╗ ██████╗ ██████╗
                  ██║    ██║██║  ██║██╔══██╗╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔══██╗
                  ██║ █╗ ██║███████║███████║   ██║   ███████╗███████║██████╔╝██████╔╝
                  ██║███╗██║██╔══██║██╔══██║   ██║   ╚════██║██╔══██║██╔═══╝ ██╔═══╝
                  ╚███╔███╔╝██║  ██║██║  ██║   ██║   ███████║██║  ██║██║     ██║
                   ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝

 ██████╗██╗  ██╗ █████╗ ████████╗    ███████╗██╗  ██╗██████╗  ██████╗ ██████╗ ████████╗███████╗██████╗
██╔════╝██║  ██║██╔══██╗╚══██╔══╝    ██╔════╝╚██╗██╔╝██╔══██╗██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝██╔══██╗
██║     ███████║███████║   ██║       █████╗   ╚███╔╝ ██████╔╝██║   ██║██████╔╝   ██║   █████╗  ██████╔╝
██║     ██╔══██║██╔══██║   ██║       ██╔══╝   ██╔██╗ ██╔═══╝ ██║   ██║██╔══██╗   ██║   ██╔══╝  ██╔══██╗
╚██████╗██║  ██║██║  ██║   ██║       ███████╗██╔╝ ██╗██║     ╚██████╔╝██║  ██║   ██║   ███████╗██║  ██║
 ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝       ╚══════╝╚═╝  ╚═╝╚═╝      ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝

         WhatsApp Chat Exporter: A customizable Android and iOS/iPadOS WhatsApp database parser
                                            Version: 0.13.0                                             
========================================================================================================
[INFO] Encryption detected on the backup!
[INFO] Trying to open the iOS backup...
[INFO] iOS backup is opened successfully
[INFO] Decrypting WhatsApp database...
WARN: decrypted 237551616 bytes of '7c7fba66680ef796b916b067077cc246adacf01d', expected 266412032 bytes!
[WARNING] Contact database not found. Skipping...
WARN: decrypted 139264 bytes of '1b432994e958845fffe8e2f190f26d1511534088', expected 180224 bytes!
[INFO] WhatsApp database decrypted successfully
Decrypting and extracting files:   0%|                                                                                                                                                                              | 1/45675 [00:00<2:10:20,  5.84file/s]WARN: decrypted 1875968 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/BackedUpKeyValue.sqlite', expected 2342912 bytes!
Decrypting and extracting files:   0%|                                                                                                                                                                              | 2/45675 [00:00<1:08:12, 11.16file/s]WARN: decrypted 114688 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/BackedUpStorageDB/BackedUpStorageDatabase.sqlite', expected 4096 bytes!
Decrypting and extracting files:   0%|                                                                                                                                                                                | 3/45675 [00:00<45:47, 16.62file/s]WARN: decrypted 139264 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/CallHistory.sqlite', expected 180224 bytes!
Decrypting and extracting files:   0%|                                                                                                                                                                                | 4/45675 [00:00<34:29, 22.07file/s]WARN: decrypted 237551616 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite', expected 266412032 bytes!
Decrypting and extracting files:   0%|                                                                                                                                                                              | 6/45675 [00:00<1:54:21,  6.66file/s]WARN: decrypted 409600 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/ExtChatDB/ExtChatDatabase.sqlite', expected 401408 bytes!
Decrypting and extracting files:   0%|                                                                                                                                                                               | 25/45675 [00:00<27:52, 27.30file/s]WARN: decrypted 659456 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/LID.sqlite', expected 708608 bytes!
Decrypting and extracting files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍| 45527/45675 [01:05<00:00, 692.78file/s]WARN: decrypted 122880 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/MessagingInfraDB_v2/MessagingInfraDatabase.sqlite', expected 4096 bytes!
Decrypting and extracting files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍| 45529/45675 [01:05<00:00, 692.79file/s]WARN: decrypted 417792 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/Sticker.sqlite', expected 479232 bytes!
Decrypting and extracting files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▌| 45557/45675 [01:05<00:00, 692.75file/s]WARN: decrypted 380928 bytes of 'AppDomainGroup-group.net.whatsapp.WhatsApp.shared/statusDB/Status.sqlite', expected 4096 bytes!
[INFO] All required files are decrypted and extracted in 1 minute 5 seconds                                                                                                                                                                               
[INFO] Processed 699 contacts in less than a second                                                                                                                                                                                                       
Traceback (most recent call last):                                                                                                                                                                                                                        
  File "/Users/alexandre/.pyenv/versions/3.14.0/bin/wtsexporter", line 6, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/alexandre/.pyenv/versions/3.14.0/lib/python3.14/site-packages/Whatsapp_Chat_Exporter/__main__.py", line 909, in main
    process_messages(args, data)
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^
  File "/Users/alexandre/.pyenv/versions/3.14.0/lib/python3.14/site-packages/Whatsapp_Chat_Exporter/__main__.py", line 586, in process_messages
    message_handler.messages(
    ~~~~~~~~~~~~~~~~~~~~~~~~^
        db, data, args.media, timing, args.filter_date,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        filter_chat, args.filter_empty, args.no_reply_ios
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/Users/alexandre/.pyenv/versions/3.14.0/lib/python3.14/site-packages/Whatsapp_Chat_Exporter/ios_handler.py", line 256, in messages
    invalid = process_message_data(message, content, is_group_message, data, message_map, no_reply)
  File "/Users/alexandre/.pyenv/versions/3.14.0/lib/python3.14/site-packages/Whatsapp_Chat_Exporter/ios_handler.py", line 287, in process_message_data
    return process_metadata_message(message, content, is_group_message, data)
  File "/Users/alexandre/.pyenv/versions/3.14.0/lib/python3.14/site-packages/Whatsapp_Chat_Exporter/ios_handler.py", line 356, in process_metadata_message
    message.data = _parse_group_action(content["ZTEXT"], data)
                   ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/alexandre/.pyenv/versions/3.14.0/lib/python3.14/site-packages/Whatsapp_Chat_Exporter/ios_handler.py", line 339, in _parse_group_action
    if "@" in entity:
       ^^^^^^^^^^^^^
TypeError: argument of type 'NoneType' is not a container or iterable

Probably related to the code in this file

entity = metadata.get('author', 'Someone')
if entity is not "Someone":
    ...
    if "@" in entity:

As there is no contact, it fails