> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/cli/help/troubleshooting/reference-does-not-resolve.md).

# A secret reference doesn't resolve

Fix a devo:// reference that Devolutions CLI can't resolve: invalid syntax, wrong workspace, entry or field not found, or a field the workspace can't read.

`devo secret run`, `devo secret read`, `devo secret inject`, or an AI client can't turn a `devo://` reference into a value. With `devo secret run`, Devolutions CLI stops before your program starts, so nothing runs with a missing secret.

## Why it happens

* The reference isn't written correctly (`invalidSecretReference`).
* The reference points at another workspace than the selected context.
* The vault, entry, or field doesn't exist, or your account can't read it.
* The workspace type can't read that field, or that form of reference.
* A template uses a variable that isn't set.

{% hint style="info" %}
Test a reference without reading any secret: `devo secret run --check --env-ref TEST=<reference> -- <your-command>` checks that the command exists and that every reference is well formed, without reading any secret or starting the command. See [Run a command with its secrets](/cli/guides/secrets/run-with-secrets.md).
{% endhint %}

## Fix it

{% stepper %}
{% step %}

### Copy the reference again

Most problems disappear when you copy the reference from Devolutions CLI instead of typing it:

```bash
devo entry references "<entry-name>" --vault-name "<vault-name>"
```

It lists every reference of the entry, never the values. On Devolutions Server, the list contains canonical references (`devo://ws/…/vault/…/entry/…/field/…`). Use them as they are. See [Find the reference to a secret](/cli/guides/secrets/find-a-reference.md).
{% endstep %}

{% step %}

### Fix the syntax

`invalidSecretReference` comes with a message that says what's wrong:

<table><thead><tr><th width="330">MESSAGE</th><th>FIX</th></tr></thead><tbody><tr><td>"Secret reference must start with 'devo://'."</td><td>Add the <code>devo://</code> prefix.</td></tr><tr><td>"Use devo://&#x3C;workspace>/&#x3C;vault>/&#x3C;entry>/&#x3C;field> or devo://&#x3C;workspace>/&#x3C;vault>/&#x3C;entry>/&#x3C;section>/&#x3C;field>."</td><td>A named reference has four parts, or five with a section. Check for a missing or extra <code>/</code>. A name that contains a <code>/</code> must be written <code>%2F</code>.</td></tr><tr><td>"Secret reference path segments cannot be empty."</td><td>Remove the double <code>//</code> inside the path.</td></tr><tr><td>"Canonical ID references must use devo://ws/&#x3C;id>/vault/&#x3C;id>/entry/&#x3C;id>/field/&#x3C;field>."</td><td>Keep the words <code>ws</code>, <code>vault</code>, <code>entry</code>, and <code>field</code> in that order, each followed by its value.</td></tr><tr><td>"Secret references do not support URI fragments."</td><td>Remove the <code>#</code> and what follows it.</td></tr></tbody></table>

`unsupportedSecretAttribute` means the `?attribute=` part isn't one of `value`, `type`, `id`, `title`, `purpose`, or `otp`. It also appears when a command needs the secret value, for example `devo secret run`, and the reference asks for another attribute: on every workspace type, a value can only come from `value`. Remove the `?attribute=` part, or set it to `value`. The value-free attributes `type`, `id`, `title`, and `purpose` work with `devo secret read` and `devo secret get` on all three workspace types. The complete syntax is in [Secret reference syntax](/cli/reference/secret-references.md).
{% endstep %}

{% step %}

### Use the right context

The first part of a named reference is the workspace. On Devolutions Cloud and Devolutions Server, it must match the selected context, or Devolutions CLI refuses with `providerSelectionChanged`: "The secret reference workspace does not match the selected cloud source context."

1. Check the selected context:

   ```bash
   devo status
   ```
2. Run the command with the context the reference belongs to:

   ```bash
   devo secret run --context <context-name> --env-ref DB_PASSWORD=<reference> -- <your-command>
   ```

To make that context the default, use `devo context use <context-name>`. See [Switch between workspaces](/cli/guides/connect/switch-workspaces.md).
{% endstep %}

{% step %}

### Check that the entry and the field exist

* `entryNotFound` or `vaultNotFound`: the name doesn't match anything your account can see. Check the spelling with `devo entry list "<entry-name>" --vault-name "<vault-name>"`. A renamed entry breaks a named reference: switch to the canonical reference, which uses IDs and survives renames.
* `entrySelectorAmbiguous`: several entries share that name. Use the canonical reference.
* `serverSecretNotFound`: Devolutions Server didn't find the field, or this account isn't allowed to read it.
* `cloudSecretFieldUnavailable`: Devolutions Cloud can't return that field for this entry. Check that the field is filled in.
  {% endstep %}

{% step %}

### Use a field the workspace can read

Each workspace type reads different fields. `devo secret capabilities` lists them without reading any secret.

* **Devolutions Cloud** reads the main fields of an entry, such as `password`, `username`, `domain`, `host`, `port`, `url`, and `privatekey`, without a section. A reference with a section stops with `unsupportedSecretField`.
* **Devolutions Server** reads one entry data property, such as `password` or `username`, without a section.
* `--stdin-reference` of `devo secret run` takes one exact `devo://` reference, named or canonical. Anything else stops with `invalidSecretStdinReference`.
  {% endstep %}

{% step %}

### Set the variables the reference uses

In a template filled by `devo secret inject`, a reference can contain environment variables, such as `devo://${WORKSPACE}/…`, with an optional default value: `${WORKSPACE:-<default>}`. `missingSecretReferenceVariable` means a variable isn't set and has no default: "Environment variable '\<name>' is required by the secret reference." Set it in the terminal or pipeline that runs the command. A `${` without its closing `}` is refused too. See [Fill a configuration file from a template](/cli/guides/secrets/fill-a-template.md).
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
`devo secret run` refuses a reference written as an argument of your command (`secretLaunchArgumentReference`). Pass it with `--env-ref`, `--stdin-reference`, or a launch manifest instead.
{% endhint %}

## Still failing?

Make sure you're signed in: an expired session also stops resolution. See [Sign-in fails or the session expired](/cli/help/troubleshooting/sign-in-fails.md). Then [collect diagnostics](/cli/help/troubleshooting/collect-diagnostics.md) and contact [Devolutions support](https://devolutions.net/support/). Send the reference if you like, it holds no secret, but never the value.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/cli/help/troubleshooting/reference-does-not-resolve.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.