Troubleshoot Ravenstash package clients

Start with the exact setup shown on the repository page. Most client failures come from a mismatched host, repository path, token owner, or environment variable.

Authentication fails

Check the following:

1. The token is active and has not been rotated, revoked, or deleted.
2. The token targets the account that owns the repository, its grants include the operation, and any member access is still valid.
3. The environment variable is available to the actual package-manager process.
4. The username is __token__ where the generated setup requires a basic-auth username.
5. npm auth configuration includes the full host and repository path.
6. Maven’s <server> ID matches its repository or distribution-management ID.

The repository or package cannot be found

• Copy the name-based or ID-based repository target from the app.
• Confirm the repository supports the requested PyPI, npm, Maven, or OCI package format.
• Open the repository’s Quick start tab, select that format, and compare its generated URL with the client configuration.
• Check whether the repository was renamed.
• Confirm you are using the download host for installs and the upload host for publication.
• Verify letter case and ecosystem-specific package naming.
• Confirm the requested package version exists and has not been deleted. A deleted version sits in the repository trash for seven days and can be restored from there.

A publish command targets the wrong host

Uploads use push.{kind}.rvsta.sh. Downloads and dependency resolution use {kind}.rvsta.sh; private mirrors use mirror.{kind}.rvsta.sh.

Action	Host family
Publish or deploy	push.pypi.rvsta.sh, push.npm.rvsta.sh, or push.maven.rvsta.sh
Install or resolve	pypi.rvsta.sh, npm.rvsta.sh, or maven.rvsta.sh

A public dependency does not resolve

1. Confirm the repository’s official upstream is enabled.
2. Confirm it is connected to the requested ecosystem.
3. Check the explicit minimum and maximum package age on the selected upstream connection, or whether new releases are allowed immediately.
4. Verify the package and version exist in the official upstream registry.
5. Confirm the request is going through the correct private Ravenstash repository URL.
6. Retry metadata resolution after checking the client is not using a stale negative cache.

If the package exists in more than one source, Ravenstash selects one source for the whole package and does not combine versions unless a Version-level rule matches it. Check How upstream package resolution works for source order and shadowed-package behavior.

A version I expect from an upstream is missing

The version exists in a connected source, but an install through the repository cannot find it.

1. Open the package in the repository. A version marked Shadowed, Reserved, or Excluded exists in a source but is not served through this repository. Select the mark to see why.
2. Check whether the package name also exists in this repository or in an earlier upstream. By default the first source that has the package supplies all of its versions, so later sources are shadowed even when they have a newer version.
3. Open the repository’s Rules tab and check whether a rule matches the package name. A rule can leave upstreams out, for example with Discard all upstreams or Resolve from the next private upstream, and a Version-level rule can leave this repository itself out.
4. Under a Version-level rule, check whether an earlier source has the same version number, including in its trash. That version is not taken from a later source.
5. Check the connection’s minimum and maximum package age on the Upstreams tab.
6. Refresh the package manager’s local cache and retry.

To let several sources supply different versions of one package, add a Version-level rule. See Package resolution rules and its Questions and troubleshooting section.

A package resolution rule does not behave as expected

Symptom	Where to look
A name you reserved answers “not found”	A name I reserved answers “not found”
A public version of a name you own was installed	An unexpected version was installed
Ravenstash refuses the rule	Ravenstash refuses my rule
A rule change has no effect on a build, or an install reports a checksum mismatch	When changes take effect
A rule is marked No upstream left or No source left after an upstream was removed	Remove an upstream that a rule selects
A version published to the repository cannot be installed	Leave this repository out

A download fails only for large files

Small packages install, but a large package file, container image layer, or Helm chart fails. Large downloads use Turbo mode and come from a storage host instead of the Ravenstash host, so the cause is usually on the way to that host.

1. Read the host name in the error. A timeout, a refused connection, or a proxy error for a host that is not a Ravenstash host means the network blocks the storage host. See A tool or proxy can reach only Ravenstash hosts.
2. If the storage host answers 400, see The storage host answers 400.
3. If a script saves an empty or very small file, it did not follow the redirect to storage. With curl, add --location (-L).
4. Check the tool and its version in the compatibility reference.

If none of these applies, or you cannot change the tool or the network, turn Turbo mode off and retry. Every download then uses standard delivery.

The storage host answers 400

A large download ends with 400 or InvalidRequest from a host that is not a Ravenstash host, such as one ending in .r2.cloudflarestorage.com. Smaller downloads work. A client setting is sending your Ravenstash credentials to every host instead of only to Ravenstash. Fix the setting that applies:

Setting	What to do
A .netrc file with a default entry, read by pip, Poetry, or PDM 2.12.4 or earlier	Replace the default entry with a machine entry that names the Ravenstash host.
curl with --location-trusted	Use --location instead.
Coursier with pass-on-redirect=true	Remove the setting.
Another “keep credentials on redirect” option in your tool	Turn the option off.

If you cannot change the setting, turn Turbo mode off.

A tool or proxy can reach only Ravenstash hosts

Large downloads time out, are refused, or are rejected by your proxy, and the error names a host ending in .r2.cloudflarestorage.com or another storage host. Your network, proxy, or build environment allows the Ravenstash hosts but not the storage hosts that Turbo mode uses. Ravenstash cannot see this failure, so these downloads do not switch to standard delivery by themselves.

Do one of the following:

• Allow the storage hosts for Turbo mode over HTTPS.
• Turn Turbo mode off. Every download then comes from the Ravenstash hosts you already allow.

An ecosystem cannot be removed

The repository must retain at least one ecosystem, and Ravenstash removes only empty ecosystems. Delete private packages and complete any cleanup reported by the app before retrying. An ecosystem that still has content in the repository trash cannot be removed until that content is permanently deleted, which takes up to seven days. Deleting the entire repository is a different action and affects every enabled ecosystem.

Ravenstash does not bulk-copy unknown upstream packages. The first eligible request fetches and caches the package.

A member still has access after a grant is removed

Ravenstash access is additive. Removing one grant does not remove access that still comes from:

• organization or namespace administration;
• the namespace base permission;
• an organization Team attached to the namespace, or a namespace Team; or
• another direct grant.

Open the member’s Access page, or the repository’s Access tab, and review every listed source. To end all access in a namespace, remove the person from the namespace. See Base and effective access.

A member can’t see a namespace or repository

In an organization, members see only the namespaces they belong to. Check the member page’s Namespaces section, then add them to the namespace or invite them into it. See Namespace membership.

The client keeps using an old URL

Inspect project files, user-level configuration, environment variables, CI variables, container build arguments, and dependency-manager credential stores. Repository renames do not leave an alias at the previous URL.

Collect useful support information

Before contacting support, record:

• Ecosystem and package-manager version.
• The repository target and permanent ID, without including the token.
• The command shape with credentials removed.
• UTC time of the request.
• HTTP status and client error text.
• Whether the same operation succeeds from another environment.

Send the details to support@ravenstash.com. Never send the token secret.