How to Fix MongoDB Error 387 (EncounteredFLEPayloadWhileApplyingHmac)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 387 when the database finds a field level encryption payload during an HMAC step. To fix it, stop applying server-side hashing rules to fields that your client app already encrypts. In the official server list, code 387 has the name EncounteredFLEPayloadWhileApplyingHmac. It shows up when your client encryption rules clash with server hashing tasks. Fixing this error takes a quick check of your schema and driver settings. You can resolve the clash without dropping your saf

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You see mongodb error 387 when the database finds a field level encryption payload during an HMAC step. To fix it, stop applying server-side hashing rules to fields that your client app already encrypts.

In the official server list, code 387 has the name EncounteredFLEPayloadWhileApplyingHmac. It shows up when your client encryption rules clash with server hashing tasks. Fixing this error takes a quick check of your schema and driver settings. You can resolve the clash without dropping your safety rules or granting wide database permissions.

Root causes of mongodb error 387 in your database

MongoDB uses code 387 to flag a conflict during a hash-based message check. FLE stands for field level encryption. With this feature, the client driver encrypts sensitive data before sending it to the server. The server stores this protected data as a special binary payload.

Sometimes, a server task tries to run an HMAC hash function over document fields. If that task hits an encrypted binary payload instead of plain data, it stops right away. The database engine cannot compute a valid hash over a hidden client payload. It throws EncounteredFLEPayloadWhileApplyingHmac to protect data integrity and stop bad index or hash states.

This issue often starts after a schema change or a driver update. A team might add client encryption to a field like a card number or national ID. If an existing server rule still tries to hash that same field, the command fails. It can also happen when a client app sends raw encrypted payloads to the wrong collection.

How to diagnose and fix the failure in production

Start by checking your app logs to find the exact query or write that failed. Look at the collection name and the fields involved in that failed step. You do not need broad admin rights to inspect the schema and find the conflict.

MongoDB grants access through role-based rules that apply to a single database. A role can grant access down to a collection level of granularity. Give the engineer on call the built-in read role on that target database. The read role allows safe actions like find, listCollections, listIndexes, dbStats, and collStats. It does not allow write actions like insert, update, remove, or dropCollection.

MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Use those read actions to check the collection rules and index definitions. Compare the server schema with the encryption schema in your client app settings. Look for any field that appears in both the client encryption list and a server hashing step.

Once you spot the overlapping field, you have two safe ways to fix the problem. First, you can update the server workflow so it skips the encrypted field during HMAC checks. Second, you can adjust your client encryption map so it only encrypts fields that do not need server hashing.

When you are ready to apply a schema or index fix, use a role with write rights. The built-in readWrite role includes all read actions plus insert, update, remove, createIndex, and dropIndex. Grant readWrite only for the window needed to update the collection or index rules. Test a single write from staging to confirm that code 387 no longer appears.

Preventing payload conflicts across database teams

Clear schema rules keep encryption errors out of production. Keep your client encryption maps in version control right next to your database index definitions. When a developer marks an email or phone number for client encryption, review the server rules first.

Run automated checks in your test pipeline before pushing schema updates to live clusters. A test write with real driver encryption settings will catch code 387 early. Keep database roles tight so developers cannot change collection rules by hand in live clusters. Rely on scoped roles and central access controls to keep data workflows predictable and safe.

Add command guardrails and field masking beside MongoDB

Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev sits inline in the wire protocol beside your database as a sidecar for your MongoDB. For every command an agent or human sends in production, hoop.dev decides to pass, mask, block, or escalate it for review.

Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run or hold risky calls for approval, and data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.

Frequently asked questions

What does EncounteredFLEPayloadWhileApplyingHmac mean in MongoDB?

It means the database engine found a client-encrypted field while trying to compute an HMAC hash. The server stops the command because it cannot hash an encrypted FLE binary payload directly.

Which MongoDB role do I need to inspect collections for error 387?

You only need the built-in read role on the affected database. It lets you run find, listCollections, and listIndexes to inspect schemas without risking accidental data changes.

Does fixing mongodb error 387 require turning off field level encryption?

No, you should keep field level encryption active for sensitive fields. Instead, remove the encrypted field from the server-side HMAC or indexing step that triggered the conflict.

The query runs. The emails stay hidden.