Troubleshoot Errors
Troubleshoot Local Atlas Deployment Issues
Local Machine Issues
If the Atlas CLI slows down to an unusable state after you create multiple local Atlas deployments and load data, you might have reached the limits of your machine.
If you're working on Docker Desktop for Windows or MacOS, consider allocating more memory.
Docker Issues
The Atlas CLI uses Docker for
atlas deployments
commands.
For MacOS or Windows, install Docker Desktop v4.31+.
For Linux, install Docker Engine v27.0+.
If your local Atlas deployment doesn't work, you might need to clean up your Docker environment and start fresh:
docker stop $(docker ps -a -q) && docker system prune -a
Run Diagnostics
If you run into issues and with atlas deployments
commands and need
support, run the following command to provide detailed diagnostics:
atlas deployments diagnostics <deploymentName> --output json > out.json
Command Errors
Error: missing credentials
Ensure that you either:
Run
atlas config init
and add your API keys to your profile or add your API keys to your environment variables. If you created a profile with a custom name or are using more than one profile, specify the correct profile with the--profile
flag.Run
atlas auth login
to authenticate using your Atlas login credentials and an authentication token.
To learn more, see Connect from the Atlas CLI.
atlas: command not found
The atlas
executable might be in a directory that isn't in your
$PATH. You can either add the directory to your $PATH, move the
executable to a directory which is in your $PATH, or run the executable
directly from its location.
400 (request "TENANT_ATTRIBUTE_READ_ONLY") The attribute pitEnabled is read-only for tenant clusters and cannot be changed by the user.
This error might appear if you try to run atlas clusters create
with the --backup
argument for a shared cluster. The
--backup
argument is unavailable for clusters smaller than M10
.
401 (request "Unauthorized") You are not authorized for this resource.
The credentials you provided aren't valid for the project specified in your Atlas CLI command. Check your public and private key strings for accuracy.
If your credentials are stored in a configuration file, make sure that the configuration file is in the
correct location. To learn more, see Locate the Configuration File. If
the Atlas CLI can't find your configuration file and you don't
store credentials in environment variables,
a 401
error will result.
401 (request "Unauthorized") Current user is not authorized to perform this action.
The user account or API key that you used to connect to the Atlas CLI doesn't have permission to perform the requested action. User accounts and API keys must have the appropriate user roles to run Atlas CLI commands. To assign or change a user's roles, see:
401 (request "Unauthorized") The currently logged in user does not have the group creator role in organization <org-id>.
This error might appear when trying to create a new
project. The user account or API
key that you use to authenticate must have the
Organization Project Creator
role at the
organization level in order
to create new projects.
403 (request "Forbidden") IP address <ip-address> is not allowed to access this resource.
The user's IP address that you use to authenticate is not on the access list for the requested project. Add your IP address to the access list to run commands.
To learn more, see the following pages:
For project access lists, see Configure IP Access List Entries.
For API key access lists, see Get Started with the Atlas Administration API.
To add your IP address to an API key's access list:
Go to the Access Manager page for your project.
If it isn't already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
Select your desired project from the list of projects in the Projects page.
Next to the Projects menu, expand the Options menu, then click Project Settings.
Click Access Manager in the navigation bar.
404 (request "Not Found") An invalid group ID <group-id> was specified.
The project ID entered with the command does not exist. Check your project ID by navigating to the Settings sub-section of the Project section in the Atlas left-side navigation.
Note
group ID
and project ID
are synonymous in MongoDB cloud services.
Alert Config Not Deleted
This error might appear if the Atlas CLI can't delete the alert configuration specified by the ID.
Configuration Errors
Blank output when reading home directory
This error might appear if the Atlas CLI can't access your home directory.
HOMEDRIVE, HOMEPATH, or USERPROFILE are blank
This error might appear if the Atlas CLI can't access your home directory.