# Troubleshooting

> Common shdctl errors and resolutions

If a shdctl command fails, rerun the command with `--log-level debug` to view detailed error output. Common issues are listed below.

## "authentication required", "authentication failed for registry", "no credentials found for registry", "no credentials configured"

`shdctl release pull` could not authenticate to the registry. Run `shdctl configure <registry>` to store, or replace, your credentials for it. For more information, refer to [Configure registry credentials](./install.md#configure-registry-credentials).

## "manifest not found in context"

Ensure that `manifest.yaml` exists in the current directory or a parent directory, or name it with `--manifest <path>`. The same error follows a `manifest.yaml` that the search finds but cannot parse: the `Failed to load manifest` warning logged just before it names the problem. A file you name with `--manifest` never gets this far: when it is missing or cannot be parsed, the command stops at once with `--manifest <path>: failed to read manifest file` or `failed to parse manifest file`, followed by the reason.

## "secrets file does not exist"

Run `shdctl secret generate` first to create the secrets file. For more information, refer to [shdctl secret](./commands/secret.md).

## "shdctl version X is older than the minimum required version Y"

Your shdctl binary is older than the version required by the release package you pulled. Upgrade shdctl to at least the version shown in the error message. A binary installed before the rename prints `vpctl version X is older than …` instead: [install shdctl](./install.md). To bypass this check temporarily, use `--skip-version-check`.

## "extracted release contains two release packages"

The extraction directory holds a release from before the "onprem" → "shd" rename next to the one you pulled. Re-pull with `shdctl release pull --clean-output`.

## "the release uses \_arrayMerge, which this shdctl does not support"

The extracted release predates Self-Hosted Deployment 2.0.0, and shdctl cannot generate it. Set `releaseVersion` to 2.0.0 or later and re-pull with `--clean-output` — or, to regenerate the older release, use the vpctl version it shipped with.

## "file already exists" during `release pull`

The extraction directory already holds a release. Re-run with `--clean-output`, which empties the directory first; the archive the failed run downloaded is still on disk.

## "failed to pull artifact"

* Check that the version exists in the registry. Self-Hosted Deployment 2.0.0 and later are not published where vpctl looks for releases — pull them with shdctl ([install it](./install.md))
* Ensure that you can access the registry over the network

Wrong credentials don't produce this message: they're reported as "authentication failed for registry", the first entry above.

## Getting more detail

Append `--log-level debug` to any command to view detailed log output.