> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

export const TroubleshootSolution = ({children}) => <>
    <hr className="my-3 w-full" />
    <details className="mt-3">
      <summary className="cursor-pointer font-semibold text-base mb-1">
        Solution
      </summary>
      <div className="mt-2 ml-4" data-component-part="step-content">
        {children}
      </div>
    </details>
  </>;

export const TroubleshootCause = ({children}) => <details className="mt-3 mb-2">
    <summary className="cursor-pointer font-semibold text-base mb-1">
      Cause
    </summary>
    <div className="mt-2 ml-4" data-component-part="step-content">
      {children}
    </div>
  </details>;

export const TroubleshootTitle = ({children}) => <>
    <p className="m-0 font-semibold text-xl leading-tight mb-2" role="heading" aria-level={3}>
      {children}
    </p>
    <hr className="my-3 w-full" />
  </>;

export const Troubleshoot = ({children}) => <div className="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border troubleshoot-admonition dark:troubleshoot-admonition" data-callout-type="troubleshoot">
    <div className="mt-0.5 w-4">
      <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" className="w-4 h-4" aria-label="Troubleshoot">
        <path d="M541.4 162.6C549 155 561.7 156.9 565.5 166.9C572.3 184.6 576 203.9 576 224C576 312.4 504.4 384 416 384C398.5 384 381.6 381.2 365.8 376L178.9 562.9C150.8 591 105.2 591 77.1 562.9C49 534.8 49 489.2 77.1 461.1L264 274.2C258.8 258.4 256 241.6 256 224C256 135.6 327.6 64 416 64C436.1 64 455.4 67.7 473.1 74.5C483.1 78.3 484.9 91 477.4 98.6L388.7 187.3C385.7 190.3 384 194.4 384 198.6L384 240C384 248.8 391.2 256 400 256L441.4 256C445.6 256 449.7 254.3 452.7 251.3L541.4 162.6z" />
      </svg>
    </div>
    <div className="prose min-w-0 w-full">{children}</div>
  </div>;

Common issues and solutions for the Anaconda CLI. If your issue is not covered here, [submit feedback](/docs/cli-reference/anaconda-cli/self-update#submit-feedback). Include the output of `ana --version`, your operating system, and the error message. Remove credentials before sharing logs.

<Troubleshoot>
  <TroubleshootTitle>
    ### `ana: command not found` after installation
  </TroubleshootTitle>

  <TroubleshootCause>
    The installation directory is not in your shell's PATH, or your shell session hasn't picked up the updated profile yet.
  </TroubleshootCause>

  <TroubleshootSolution>
    1. Open a new terminal window or tab.
    2. If ana is still not found, check that it exists in the installation directory. The default is `~/.local/bin/ana` on macOS/Linux or `%USERPROFILE%\.local\bin\ana.exe` on Windows.
    3. If needed, add the directory to PATH for your current session:

    <Tabs>
      <Tab title="Windows">
        ```powershell theme={null}
        $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
        ```

        To keep the change, add the installation directory to your user `Path` variable in Windows settings.
      </Tab>

      <Tab title="macOS/Linux">
        ```sh theme={null}
        export PATH="$HOME/.local/bin:$PATH"
        ```

        Add this line to your shell profile, such as `~/.bashrc` or `~/.zshrc`, to keep the change.
      </Tab>
    </Tabs>

    If you chose a custom installation directory, use that directory instead. If you installed ana with conda, activate the environment containing it.
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>
    ### Keyring error when running `ana whoami` or `ana login`
  </TroubleshootTitle>

  <TroubleshootCause>
    The keyring file is corrupted or contains credentials in an unexpected format.
  </TroubleshootCause>

  <TroubleshootSolution>
    1. Log out to clear the stored credentials:

       ```sh theme={null}
       ana logout
       ```

    2. Log in again:

       ```sh theme={null}
       ana login
       ```

    If logout also fails, check the keyring file's permissions before resetting it. The default location is:

    <Tabs>
      <Tab title="Windows">
        `%USERPROFILE%\.anaconda\keyring`
      </Tab>

      <Tab title="macOS/Linux">
        `~/.anaconda/keyring`
      </Tab>
    </Tabs>

    If `ANA_KEYRING_PATH` is set, check that location instead. If the file is damaged, close other applications using it and rename it to a backup with your file manager. Then run `ana login` to create a new keyring.

    <Warning>
      Keep the backup private. Resetting the keyring affects all credentials in that file, including credentials shared with other Anaconda tools. You might need to log in again to those tools.
    </Warning>
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>
    ### `ana self update` fails or cannot reach the download server
  </TroubleshootTitle>

  <TroubleshootCause>
    The download server might be unavailable, or a firewall, proxy, or certificate problem might be preventing access.
  </TroubleshootCause>

  <TroubleshootSolution>
    1. Verify you can reach the server:

       ```sh theme={null}
       curl --head --fail --show-error --location https://anaconda.sh/releases.json
       ```

    2. If `ANA_SELF_UPDATE_URL` is set, check that update source instead. For a corporate proxy or certificate error, check the settings with your administrator. Do not disable certificate verification.

    3. Once access is restored, run `ana self update --list` to check available versions. If the download still fails, follow the [Installation instructions](/docs/cli-reference/anaconda-cli/getting-started).

           <Note>
             Use `--list`, not `--check`, for a check that cannot install an update. After updating, run `ana --version` to verify the result. An update error can be printed even when the command returns a successful exit code.
           </Note>
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>
    ### Permission denied when writing to the keyring or install directory
  </TroubleshootTitle>

  <TroubleshootCause>
    The `~/.anaconda/` directory or the install directory has incorrect file permissions, often caused by running a previous installation with elevated privileges.
  </TroubleshootCause>

  <TroubleshootSolution>
    On macOS/Linux, if you own the default keyring directory and file, restore private access:

    ```sh theme={null}
    chmod 700 "$HOME/.anaconda"
    chmod 600 "$HOME/.anaconda/keyring"
    ```

    Run the second command only if the file exists. If you use a custom keyring location, check that file's permissions instead.

    On Windows, check the affected file's **Security** properties. If another user owns the files or your organization manages the installation, ask an administrator to correct access to the affected path. Do not change permissions across an entire shared installation directory or make credentials readable by other users.
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>A requested version is not available</TroubleshootTitle>

  <TroubleshootCause>
    The version might not be available from your selected update source.
  </TroubleshootCause>

  <TroubleshootSolution>
    To see which versions you can install, run:

    ```sh theme={null}
    ana self update --list
    ```

    Check your [Update source settings](/docs/cli-reference/anaconda-cli/self-update#update-sources-and-prereleases). Development releases can differ between the default server and GitHub Releases. To switch to an older release, specify its version; updating without a version does not downgrade ana.
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>Self-update is unavailable</TroubleshootTitle>

  <TroubleshootCause>
    Conda manages updates when you install ana as a conda package.
  </TroubleshootCause>

  <TroubleshootSolution>
    Activate the environment containing ana and run:

    ```sh theme={null}
    conda update ana-cli
    ```

    Use conda rather than replacing its executable with a separately downloaded binary.
  </TroubleshootSolution>
</Troubleshoot>