How to Fix MongoDB Error 491 (CommandNotSupportedOnLegacyTimeseriesBucketsNamespace)
You trigger mongodb error 491 when you run an unsupported command on a legacy time series bucket namespace. You fix it by sending queries to the main time series collection instead of the internal bucket namespace. The database engine maps this failure to the official name CommandNotSupportedOnLegacyTimeseriesBucketsNamespace. It stops users and apps from breaking how the database stores time series data under the hood. What causes mongodb error 491 in your database Time series collections s
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 trigger mongodb error 491 when you run an unsupported command on a legacy time series bucket namespace. You fix it by sending queries to the main time series collection instead of the internal bucket namespace.
The database engine maps this failure to the official name CommandNotSupportedOnLegacyTimeseriesBucketsNamespace. It stops users and apps from breaking how the database stores time series data under the hood.
What causes mongodb error 491 in your database
Time series collections store measurements in grouped documents called buckets. In older database setups, the engine kept these buckets in a separate system namespace.
Apps or engineers sometimes target that underlying bucket namespace by mistake. The database blocks commands that do not work with that older bucket format.
When a script or client tool sends one of these blocked commands, the server returns code 491. This often happens during manual schema checks, backup runs, or custom maintenance scripts.
Legacy monitoring tools can also cause this problem. They may scan all namespaces in a database and run admin commands against each one.
When the scan hits a legacy time series bucket namespace, the database rejects the command. The error protects the internal data layout from bad writes or invalid reads.
How to diagnose and fix the failure safely
Start by checking your database logs to find which client or user sent the failed command. Look for code 491 and note the exact namespace target in the log entry.
Next, inspect the app code or admin script that triggered the error. Change the target name so it points to the primary time series collection.
Standard read and write operations work as expected when you use the main collection name. The database engine handles the bucket logic for you behind the scenes.
Customer Support Access to Production + MongoDB Authentication & Authorization: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
You should also review the database roles assigned to your users and apps. MongoDB grants access through roles that define allowed actions down to the collection level.
The built-in read role grants access to non-system collections through actions like find and listCollections. It keeps users away from internal system namespaces while letting them read standard time series data.
If an engineer only needs to check data, assign the read role on that database. Do not grant broad admin privileges that let scripts touch internal bucket namespaces.
When an app needs to add or update time series records, use the readWrite role. This role adds actions like insert, update, and remove on normal collections without exposing internal buckets.
How to prevent legacy namespace errors during maintenance
Many teams hit this error when engineers run manual queries during an incident. An engineer might list all namespaces and run a write command on the wrong target.
You can stop this by scoping roles down to the exact collections a team needs. Collection-level roles stop accidental commands against legacy system buckets before they run.
Also check your backup and migration scripts in a staging setup before production runs. Make sure those tools understand time series collections and skip direct commands on legacy bucket namespaces.
If you also store sensitive fields like emails or phone numbers, add data masking to your query path. Masking rewrites matched fields in results while engineers debug failed queries in production.
Inspect MongoDB wire traffic in flight
Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev sits inline in the MongoDB protocol next to your server as a sidecar for your MongoDB. On every production command from mongosh, drivers, or AI agents, hoop.dev decides whether to pass, mask, block, or hold it for human review.
First, hoop.dev guardrails block bad deletes, drops, and write pipelines or hold them for approval. Next, hoop.dev data masking rewrites sensitive values in returned documents in memory and logs each decision. Explore the repo on GitHub.
Frequently asked questions
What does CommandNotSupportedOnLegacyTimeseriesBucketsNamespace mean?
It is the official name for error code 491 in MongoDB. It means a client sent an invalid command directly to an internal legacy time series bucket namespace.
Can I fix this error by giving my user a higher role?
No, adding more privileges will not make the database accept an unsupported command. You must point your query at the main time series collection instead of the bucket namespace.
How do built-in roles help prevent this error?
The built-in read and readWrite roles grant access to non-system collections only. Using them stops users and apps from running direct commands on internal system bucket namespaces.
Short role checks help teams work fast. Simple rules make each review clear. Good logs keep every team safe. Scoped keys stop bad changes early.
Related guides
In this post