How to Fix MongoDB Error 422 (StreamProcessorAtlasUnauthorizedError)

Published
Length
3 min read

Luis Felipe Dias

All posts

You see mongodb error 422 when a stream processor lacks the right permissions in Atlas. You can fix it by updating the database user role to allow the needed actions. This failure uses the official name StreamProcessorAtlasUnauthorizedError in the database engine. The engine places this issue in two distinct error groups. The first group is StreamProcessorUserError, and the second group is StreamProcessorRetryableError. This means a user setup mistake caused the stop, but the job can try again.

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 422 when a stream processor lacks the right permissions in Atlas. You can fix it by updating the database user role to allow the needed actions.

This failure uses the official name StreamProcessorAtlasUnauthorizedError in the database engine. The engine places this issue in two distinct error groups. The first group is StreamProcessorUserError, and the second group is StreamProcessorRetryableError. This means a user setup mistake caused the stop, but the job can try again. Once you grant the missing rights, the stream can pick up its work.

What causes mongodb error 422 in stream processors

MongoDB controls all data access through role-based rules. A role gives a user the right to run specific actions on a resource. Each role applies to the database where an admin defines it. Roles can also narrow those rights down to a single collection. Note that Atlas database users have different built-in roles than self-hosted users. Even so, both setups build their roles from the same basic privilege actions.

Stream processors must read incoming events or write output to target collections. When the assigned user lacks those specific actions, the engine blocks the request. It then throws code 422 and stops the current task. Because the engine marks this error as retryable, the processor may keep trying. Every retry will fail until you change the user role or target collection.

Often, a processor needs to watch a source using the changeStream action. In other cases, the processor must write data out to a target collection. If the user only holds basic read rights, any write step will fail. A mismatch between the job needs and the role rules triggers this error.

How to diagnose and fix the permission failure safely

Start by checking the logs for your active stream processor job. Find the exact database and collection the processor tried to use when it failed. Next, check the database user that runs the stream processor connection. Compare the actions the job needs against the role that user holds today.

If the processor only reads data, the built-in read role is often enough. The read role grants access to all non-system collections in its database. It also covers the system.js collection. This role includes actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It does not allow insert, update, remove, or dropCollection actions.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

If your stream processor writes results to a collection, a read role will fail. You must upgrade the user to the readWrite role on that target database. The readWrite role includes everything in the read role plus data change rights. Its allowed actions include insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection.

Never fix this error by giving the user full admin rights across the cluster. Broad roles create huge security risks if a key leaks. Instead, scope the role down to the exact database or collection needed. Keep read jobs on the read role and write jobs on the readWrite role. Once you save the role update, the retryable error will clear on the next run.

How to prevent role errors during live debugging

Many teams hit code 422 when engineers test stream jobs by hand. People often share one broad account or guess which role a job needs. This habit leads to broken pipelines or unsafe permission sprawl in production.

A better path is to separate human debug work from service accounts. Give your stream processor a narrow role for its exact source and sink collections. When engineers need to inspect data, route their queries through a secure access layer. You can also add data masking to rewrite emails, phone numbers, and card numbers in query results. This keeps live data safe while teams check why a stream job failed.

Check MongoDB commands and documents on the wire

MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB, inline in the MongoDB wire protocol. On every command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13, or hold risky commands for approval. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents in memory, and every verdict is logged. See the open-source code on GitHub.

Frequently asked questions

What does StreamProcessorAtlasUnauthorizedError mean in MongoDB?

It means an Atlas stream processor tried to run an action without permission. It maps to error code 422 and stops the step until you fix the user role.

Is mongodb error 422 a permanent failure for a stream job?

No, the database marks this code as both a user error and a retryable error. Once you grant the right role actions, the processor can retry and succeed.

Does the read role allow a stream processor to watch a change stream?

Yes, the built-in read role includes the changeStream action along with find and listCollections. You only need the readWrite role if the processor also inserts or updates documents.

The query runs. The emails stay hidden.