> ## 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

Troubleshoot

### Login hangs on headless servers or SSH sessions

***

<details>
  <summary>Cause</summary>

  On versions of `anaconda-auth` older than 0.15.0, the default login flow attempts to open a web browser for OAuth authentication. If you are on a headless server, in an SSH session, or on any system without a graphical browser, this causes the login command to hang indefinitely.

  In `anaconda-auth` 0.15.0 and later, the device code flow is used by default, which does not require a local browser. If you are experiencing this issue, you are likely running an older version.
</details>

***

<details>
  <summary>Solution</summary>

  Update `anaconda-auth` to 0.15.0 or later, which uses the device code flow by default:

  ```sh theme={null}
  conda install "anaconda-auth>=0.15.0"
  ```

  If you cannot update, use one of the following workarounds:

  > [accordion] Enable device flow with an environment variable
  >
  > Set the `ANACONDA_AUTH_USE_DEVICE_FLOW` environment variable before running the login command:
  >
  > ```sh theme={null}
  > export ANACONDA_AUTH_USE_DEVICE_FLOW=1
  > anaconda auth login
  > ```
  >
  > The CLI prints a verification URL and a one-time code. Open the URL on any device with a browser, enter the code, and the login completes on the headless system.

  > [accordion] Configure device flow permanently for a site
  >
  > Use `anaconda sites modify` to enable device flow for the configured site:
  >
  > ```sh theme={null}
  > anaconda sites modify --use-device-flow <SITE_NAME>
  > ```
  >
  > After this, all future `anaconda auth login` calls for that site use device flow.

  > [accordion] Use an API key environment variable
  >
  > If you do not need interactive login (for example, in CI/CD pipelines or automated scripts), bypass the login flow entirely by setting an API key:
  >
  > ```sh theme={null}
  > export ANACONDA_AUTH_API_KEY=$(anaconda auth api-key)
  > ```
  >
  > On a system where you cannot run `anaconda auth api-key` directly, retrieve the key on another machine first and inject it through your platform's secrets management (for example, GitHub Actions secrets or a vault).
</details>

Troubleshoot

Unauthorized (401) error when uploading or managing packages

***

<details>
  <summary>Cause</summary>

  Your authentication token is missing, expired, or does not have the required scopes.
</details>

***

<details>
  <summary>Solution</summary>

  Run `anaconda login` to re-authenticate:

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

  When using a token, verify that the token has the required scopes by running `anaconda auth --info`:

  ```sh theme={null}
  anaconda auth --info
  ```

  To create a new token with the required scopes, see the [`anaconda auth`](https://anaconda.com/docs/cli-reference/anaconda-client/commands/auth) command reference.
</details>

Troubleshoot

Package not found (404) error

***

<details>
  <summary>Cause</summary>

  The package spec is incorrect, the package does not exist, or you do not have permissions to access the package.
</details>

***

<details>
  <summary>Solution</summary>

  Verify the package spec format (`USER/PACKAGE/VERSION`) by running `anaconda org show` with your spec:

  ```sh theme={null}
  anaconda org show <SPEC>
  ```

  If the package is private, verify you are logged in with an account that has permissions to access the package.
</details>

Troubleshoot

SSL certificate verification failed

***

<details>
  <summary>Cause</summary>

  Your system's SSL certificates are out of date, or you are behind a corporate proxy with a custom certificate authority.
</details>

***

<details>
  <summary>Solution</summary>

  Update your root certificates to the latest version, or disable SSL verification in your configuration:

  ```sh theme={null}
  anaconda org config --set ssl_verify false
  ```

  > [!WARNING]
  >
  > Do not disable SSL verification in production. Doing so exposes your credentials to potential interception.
</details>

Troubleshoot

Upload fails with "file already exists"

***

<details>
  <summary>Cause</summary>

  A file with the same name and version already exists in the target label.
</details>

***

<details>
  <summary>Solution</summary>

  Use `--force` to overwrite the existing file, or `--skip-existing` to skip files that are already uploaded:

  > [tab] Overwrite
  >
  > ```sh theme={null}
  > anaconda org upload mypackage.conda --force
  > ```

  > [tab] Skip
  >
  > ```sh theme={null}
  > anaconda org upload *.conda --skip-existing
  > ```
</details>