# uip vss deploy

> Syntax and options for `uip vss deploy`, which installs, upgrades, or downgrades a Vertical Solution package, and for `deploy status`, `resume`, and `cancel`.

`uip vss deploy` installs, upgrades, or downgrades a published Vertical Solution package in your tenant. The deploy runs in UiPath Cloud as the identity you logged in with — you at a terminal, or your pipeline's external application — and with its permissions. The CLI submits the job, streams its progress, and lets you resume or cancel it. After a successful deploy, [`uip vss deploy seed`](./uip-vss-deploy-seed.md) loads the solution's Data Fabric seed data.

The same commands work interactively at a terminal and unattended in a pipeline: every prompt has a flag.

This page covers `deploy` and the subcommands that manage a deploy job.

| Command | Purpose |
|---|---|
| [`deploy`](#uip-vss-deploy) | Deploy a published Vertical Solution package: install, upgrade, or downgrade. |
| [`deploy status`](#uip-vss-deploy-status) | Show the status and step checkpoints of a deploy job. Read-only, safe to poll. |
| [`deploy resume`](#uip-vss-deploy-resume) | Resume a paused or failed deploy job from its last checkpoint, or re-attach to a running one. |
| [`deploy cancel`](#uip-vss-deploy-cancel) | Cancel a deploy job. |
| [`deploy seed`](./uip-vss-deploy-seed.md) | Load the solution's Data Fabric seed data. |

## Prerequisites

- `uip login` completed for the organization and tenant you deploy to. `uip login tenant set <tenant>` switches tenant. Refer to [`uip login`](./uip-login.md).
- The permissions your vertical needs. Each vertical documents the roles and permissions its deploy and seeding need, for a user login and for an external application. Ask your administrator to grant them. For an external application, also refer to [Set up the external application](#set-up-the-external-application).
- An existing Orchestrator folder to install into. The deploy never creates the target folder.

## uip vss deploy

### Synopsis

```
uip vss deploy [options]
```

### Deploy interactively

```bash
uip login
uip vss deploy
```

With no flags, `deploy` walks you through the deploy:

1. Pick a vertical, then a package from it. The CLI skips the vertical when only one is available.
2. When the package is already deployed, choose between upgrading it and installing a fresh copy into another folder.
3. On a fresh install, pick a target folder from the tenant's Orchestrator folders.
4. Pick a version.
5. On a fresh install, name the deployment. Leave it blank to use the solution's own name.
6. Answer the configuration values the package declares.
7. Confirm, then watch the job's steps and logs.

Pass a flag to skip its prompt. For example, `--vertical <vertical>` goes straight to the package picker. Pass all of them to skip the prompts entirely, as described in [Deploy from CI/CD](#deploy-from-cicd).

When the job finishes, the run prints the steps that ran (`Steps: ✓ pre-verify → ✓ solution → …`) and the ones that did not apply to this package. A deploy that succeeds while an optional step fails prints `Deployment succeeded — with warnings:` and names each failed step with the reason.

### Options

| Option | Description |
|---|---|
| `--package-name <name>` | Package to deploy. Required when the terminal cannot be prompted. |
| `--package-version <version>` | Version to deploy. Defaults to the newest published version for a fresh install, or the newest allowed upgrade. Required for a downgrade when the terminal cannot be prompted. At a terminal, `--action downgrade` offers the nearest older deployable version. |
| `--vertical <vertical>` | Vertical to list packages from. Used only by the interactive package picker. |
| `--action <action>` | `install`, `upgrade`, or `downgrade`. Required when the package is already deployed and the terminal cannot be prompted. |
| `--folder-path <path>` | On a fresh install, the existing Orchestrator folder to install into, as a path such as `Shared/Production` or a bare name. On an upgrade or downgrade, the folder of the deployment to change. The CLI resolves the path against Orchestrator, so a typo or an ambiguous match fails before a job exists. Must agree with `--folder-key` when you pass both. Refer to [Folder resolution](#folder-resolution). |
| `--folder-key <guid>` | Folder key of the deployment to upgrade or downgrade, or of the install target. |
| `--deployment-name <name>` | Deployment name, unique per tenant. A fresh install creates it, and it defaults to the solution's name. An upgrade or downgrade addresses the existing deployment by it. Refer to [Deployment name](#deployment-name). |
| `--config <config...>` | Configuration values as `KEY=VALUE`, space-separated. Use `KEY=env.MY_VAR` for a secret. |
| `--config-file <path>` | JSON or flat YAML file of `KEY: VALUE` pairs. `--config` wins over it, and the CLI reads an `env.NAME` value only when that value wins, so a variable that `--config` overrides does not need to be set. |
| `--resource-config <path>` | Path to `deploy-config.json`. Defaults to `./deploy-config.json`. Refer to [Per-resource configuration](#per-resource-configuration). |
| `-y, --yes` | Confirm without prompting. Required in a non-interactive terminal. |
| `--no-wait` | Submit the job and exit, printing the job ID. |
| `--timeout <seconds>` | Stop watching after this many seconds. `0`, the default, means no limit. It also closes a pause or retry prompt nobody answered, and cuts short the wait between capacity retries on a resume. |
| `--poll-interval <ms>` | Milliseconds between status polls. Default `3000`. |
| `--no-browser` | Print a pause URL instead of offering to open it. |
| `--seed` / `--no-seed` | Load Data Fabric seed data after a successful deploy, or skip the offer. `--seed` cannot be combined with `--no-wait`. Refer to [`uip vss deploy seed`](./uip-vss-deploy-seed.md). |
| `--login-validity <minutes>` | Minutes of remaining token validity that trigger a token refresh. Default `10`. |

### Folder resolution

A fresh install targets a folder with `--folder-path` or `--folder-key`. An upgrade or downgrade can pin the existing deployment's folder with either one. The folder must already exist. The deployment name decides which deployment an upgrade applies to — refer to [Deployment name](#deployment-name).

The CLI resolves `--folder-path` against Orchestrator before it submits the job. It sends a bare name to the service unresolved only on a fresh install, and only when the login cannot read the folder list, for example an external application without folder-read rights. The service then matches the name by display name.

On an upgrade or downgrade with a login that cannot read the folders, pass `--folder-key <guid>`, or address the deployment by `--deployment-name`.

### Deployment name

Every deployment has a name, unique per tenant. Automation Solutions keys upgrades and downgrades by that name: the same call creates a new deployment when the name is new and updates the existing one when it is not, regardless of the folder you target.

On a fresh install, you choose the name. It also names the folder the solution installs into, created under the target folder. Leave it blank to use the solution's own name. Give a name to install the same package into more than one folder, for example UAT and Prod.

On an upgrade or downgrade, the CLI sends the first name it finds:

1. `--deployment-name`, when you pass it.
2. The name on the service's own record of the deployment. This is the usual case.
3. No name. The service then finds the deployment in the target folder.

If the record carries no name and you know it, pass `--deployment-name`.

`uip vss deploy` cannot upgrade a deployment that the service has no record of. `--action upgrade` then fails with `needs an existing deployment, but none is installed`, and exit code `3`.

#### When the name is already taken

On a fresh install, the CLI checks the name before it submits anything:

- At a terminal, it offers to pick another name or to stop. It also offers to upgrade the existing deployment, when that deployment is the same solution, installed, on a different version.
- With no terminal, the deploy fails before it submits, and the message names the flags to pass: `--deployment-name <name>` for another name and, when an upgrade is possible, `--action upgrade --deployment-name <name> --folder-key <key>` to update the existing deployment.

The check looks up that one name in the tenant's Automation Solutions deployments. When the read is refused, the login type decides what happens:

- External application: the CLI skips the check and submits the fresh install. The refusal is a standing condition — the application has no Automation Solutions scope, or the tenant's ring only offers the older deployment search, which reads user logins only — and no retry changes it. A name that already exists then updates that deployment in place, in its own folder. A session that carries IDs and no tenant name also skips the check, because the deployment search needs a tenant name.
- User login: the deploy stops, and the message names what to ask for — a missing permission, an expired token, or a feed that does not answer. Skipping the check would let a fresh install adopt a deployment somebody else owns.

### Upgrade a deployment

```bash
# Upgrade the only installed deployment to the newest allowed version
uip vss deploy --package-name <package-name> --action upgrade --yes

# Pick which deployment when the package is installed in more than one folder
uip vss deploy --package-name <package-name> --action upgrade \
  --folder-key a1b2c3d4-e5f6-7890-abcd-ef1234567890 --yes

# A deployment whose record carries no name, from a pipeline: name it
uip vss deploy --package-name <package-name> --package-version 1.5.0 \
  --action upgrade --deployment-name my-solution-prod \
  --folder-key a1b2c3d4-e5f6-7890-abcd-ef1234567890 --yes
```

At a terminal, the version picker shows the newest upgrades and the nearest downgrade. Major versions are breaking changes and cannot be skipped: an upgrade from 1.x straight to 3.x while a 2.x exists is refused, and the CLI offers to deploy the 2.x first. A pipeline never downgrades unless `--action downgrade` and `--package-version` say so.

### Configuration values

Each Vertical Solution package declares its own configuration values in its manifest: the names, which ones are required, which are secret, and their descriptions and defaults. The set differs from package to package, and the package's own documentation describes what each key means.

To find out which keys a package declares:

- Run the deploy at a terminal. The guided flow prompts for every required key that has no value yet, and shows the package's description and default for each. Optional keys are not prompted — pass them with `--config` or `--config-file`. Stop at the final confirmation if you only want the list.
- Read the failure in a pipeline. Without a terminal, a missing required value fails before anything is submitted, and the message names the key and the `--config <KEY>=<value>` flag to pass.

Values reach the deploy from three places, in this order:

1. `--config <KEY>=<value>`. Repeat the flag, or list more than one pair, to set more than one key.
2. `--config-file <path>`, a JSON or flat YAML file of `<KEY>: <value>` pairs.
3. A prompt, at a terminal. A value the package marks required cannot be left blank.

Configuration values are not carried over from an earlier deploy, so the CLI asks for them on an upgrade too. In a pipeline, a missing required value fails before anything is submitted, and the message names the `--config` flag to pass.

For a secret, use the `env.` form. The value stays out of the command, so it never reaches shell history, `ps` output, or a CI log:

```bash
uip vss deploy --package-name <package-name> \
  --config <SECRET_KEY>=env.MY_SECRET --yes
```

`MY_SECRET` comes from the environment. In a pipeline, bind it from the secret store, such as GitHub Actions `secrets`, Azure DevOps variable groups, or `vault read`. At a terminal, read it into the variable instead of typing it into a command:

```bash
read -rs MY_SECRET && export MY_SECRET
```

### Per-resource configuration

A package can also declare per-resource configuration, such as a web app's `routingName`, the `externalClientId` of an existing external application, or any other property the author marked configurable.

An unresolved per-resource value does not fail the deploy. The job pauses until someone finishes it in the portal's configuration wizard. Supply the values up front to let a deploy run from start to finish without stopping.

How the values are collected depends on the action:

- Fresh install: the guided flow asks for each declared property that `deploy-config.json` does not supply, and shows the package's description and default.
- Upgrade: the CLI never asks, because Automation Solutions keeps the values the deployment already has. It still sends the values in `deploy-config.json`, so keep the file next to the upgrade command too. When a new version needs a value the deployment does not hold yet, the file supplies it. Otherwise, the job pauses for it in the configuration wizard.

For an unattended run, put the values in `deploy-config.json`:

```json
{
  "version": 1,
  "resources": [
    {
      "name": "Webapp",
      "configuration": {
        "routingName": "my-solution-prod",
        "externalClientId": "<your-external-app-client-id>"
      }
    }
  ]
}
```

The CLI reads the file from `./deploy-config.json`, or from the path you pass with `--resource-config`. Values in the file win over any prompt.

Before it asks you to confirm, the CLI lists each resource's property names and says which of them came from the file:

- A file picked up from the working directory is therefore never a silent input.
- The values are not printed, since any of them can be a secret.
- The listing is part of the confirmation prompt only: `--yes` submits without printing it.

On a fresh install, if a required property still has no value, the deploy goes ahead and the CLI warns, by name, that the deployment pauses for it. An upgrade or downgrade does not warn, since the existing deployment keeps its values.

The CLI never registers an external application. `externalClientId` must be the client ID of one that already exists in **Admin** > **External Applications**.

A declared per-resource property whose name looks like a secret is never asked for and never sent, because the deploy job stores per-resource values unencrypted. Set such a value in the portal's configuration wizard. The CLI checks these terms, case-insensitively:

| Kind | Terms checked |
|---|---|
| Secret | `secret` |
| Password | `password`, `passwd`, `pwd` |
| Token | `token` |
| Credential | `credential` |
| API key | `apikey`, `api-key`, `api_key` |
| Access key | `accesskey`, `access-key`, `access_key` |
| Private key | `privatekey`, `private-key`, `private_key` |
| Connection string | `connectionstring`, `connection-string`, `connection_string` |
| Passphrase | `passphrase` |

:::important
`deploy-config.json` is meant to be committed to your repository, and its values are not treated as secrets. The CLI rejects a key that contains any of the secret-looking terms in the preceding table. `--config`, also in the `KEY=env.MY_VAR` form, supplies manifest configuration values only, so set secret per-resource properties in the portal's configuration wizard.
:::

The CLI also warns about input that nothing reads:

- A `deploy-config.json` entry that names a resource the manifest does not declare as configurable is ignored, with a warning.
- A `--config` or `--config-file` key the package does not declare is sent, with a warning.
- When the manifest declares no configurable resources, named `deploy-config.json` entries are kept without a warning. When it declares no configuration values, `--config` and `--config-file` keys are sent without a warning.
- A key the deploy sets itself, such as `UIPATH_TENANT_ID`, always gets a warning, because the deploy's own value takes precedence.

### Data shape (--output json)

A watched deploy that succeeds:

```json
{
  "Code": "VerticalSolutionDeployed",
  "Data": {
    "JobId": "8f1c2a34-0000-0000-0000-000000000001",
    "Status": "succeeded",
    "PackageName": "<package-name>",
    "PackageVersion": "1.4.2",
    "Action": "install"
  }
}
```

With `--no-wait`, `Code` is `VerticalSolutionDeploySubmitted` and `Status` is the job state at submit time, for example `running`.

## uip vss deploy status

Shows the status and step checkpoints of a deploy job. The command is read-only, so it is safe to poll from CI.

### Synopsis

```
uip vss deploy status <job-id> [options]
```

### Arguments

| Argument | Description |
|---|---|
| `<job-id>` | ID of the deploy job, as printed by `uip vss deploy`. |

### Options

| Option | Description |
|---|---|
| `--login-validity <minutes>` | Minutes of remaining token validity that trigger a token refresh. Default `10`. |

### Data shape (--output json)

```json
{
  "Code": "VerticalSolutionDeployStatus",
  "Data": {
    "JobId": "8f1c2a34-0000-0000-0000-000000000001",
    "Status": "running",
    "PackageName": "<package-name>",
    "PackageVersion": "1.4.2",
    "Action": "install",
    "Steps": [{ "Key": "SOLUTION", "Status": "running" }]
  }
}
```

`Steps` lists the steps in the order they ran. `Progress: { Finished, Total }` reports how many of the job's steps have ended — succeeded, failed, or not needed — out of all of them. An optional step can fail while the job still succeeds.

Once the solution step finishes, `InstalledFolderKey` reports the folder the solution installed into. `uip vss deploy seed` uses it as the seed scope.

## uip vss deploy resume

Resumes a paused or failed deploy job from its last checkpoint, or re-attaches to one that is still running. Completed steps are not run again.

### Synopsis

```
uip vss deploy resume <job-id> [options]
```

### Arguments

| Argument | Description |
|---|---|
| `<job-id>` | ID of the deploy job to resume. |

### Options

| Option | Description |
|---|---|
| `--deployment-name <name>` | Rename a fresh install that failed because the name was already taken, or name the deployment an upgrade failed to find. |
| `--no-wait` | Resume the job and exit without watching it. |
| `--timeout <seconds>` | Stop watching after this many seconds. `0`, the default, means no limit. |
| `--poll-interval <ms>` | Milliseconds between status polls. Default `3000`. |
| `--no-browser` | Print a pause URL instead of offering to open it. |
| `--seed` / `--no-seed` | Load Data Fabric seed data once the resumed job succeeds, or skip the offer. `--seed` cannot be combined with `--no-wait`. |
| `-y, --yes` | Seed every entity without asking, when seeding runs. A resume needs no confirmation, so this option only skips the seed questions. |
| `--login-validity <minutes>` | Minutes of remaining token validity that trigger a token refresh. Default `10`. |

A resumed job that succeeds finishes the same way as a fresh deploy: when the package declares seed entities, the CLI writes the seed templates and offers the seeding step. `resume --no-wait` returns as soon as the service accepts the job, so it writes no seed context or templates and offers nothing. Follow it with `uip vss deploy status <job-id>` and, once the job succeeds, `uip vss deploy seed`.

### Examples

```bash
# Resume a paused or failed deploy job and watch it finish
uip vss deploy resume 8f1c2a34-0000-0000-0000-000000000001

# Rename a fresh install that failed on a tenant-unique name collision
uip vss deploy resume 8f1c2a34-0000-0000-0000-000000000001 \
  --deployment-name my-solution-prod-2
```

### Recover a job

Once the service accepts a deploy job, it never runs the job again on its own, so recovery is always something you ask for. The CLI does retry a submit that the service refuses for capacity, before the job exists. The way back is the same command for every cause:

| Situation | What to do |
|---|---|
| The job needs activation setup, connection authorization, or the portal's configuration wizard | At a terminal, the CLI prints the page URL and offers to open it. Do that step — for activation setup, also activate the deployment there — then press Enter, or run `uip vss deploy resume <job-id>` later. In a pipeline, the run stops with exit code `1`. Do the step, then run `uip vss deploy resume <job-id>`. |
| Your login expired while the job was running | A login that can renew its token, such as a user login, renews it and resumes on its own, with or without a terminal. A client-credentials or environment login cannot renew its token: run `uip login` again, then `uip vss deploy resume <job-id>`. |
| A step failed | Run `uip vss deploy resume <job-id>`. It restarts from the last checkpoint, not from the beginning. |
| The job was interrupted | The next status read reports it failed. Run `uip vss deploy resume <job-id>` to continue where it stopped. |
| You pressed Ctrl+C while watching | The job keeps running. Re-attach with `uip vss deploy resume <job-id>`. |
| You pressed Ctrl+C at a pause or failure prompt | The job stays paused or failed where it was. Read it with `uip vss deploy status <job-id>`, then run `uip vss deploy resume <job-id>`. |

## uip vss deploy cancel

Cancels a deploy job. A paused job stops immediately, and a running one stops at the next step boundary. Steps already applied are not rolled back.

### Synopsis

```
uip vss deploy cancel <job-id> --yes
```

### Arguments

| Argument | Description |
|---|---|
| `<job-id>` | ID of the deploy job to cancel. |

### Options

| Option | Description |
|---|---|
| `-y, --yes` | Confirm the cancellation. Required: the command never prompts. |
| `--login-validity <minutes>` | Minutes of remaining token validity that trigger a token refresh. Default `10`. |

### Data shape (--output json)

```json
{
  "Code": "VerticalSolutionDeployCanceled",
  "Data": {
    "JobId": "8f1c2a34-0000-0000-0000-000000000001",
    "Status": "running",
    "CancelRequested": true
  }
}
```

## Deploy from CI/CD

A pipeline runs the deploy the same way as every other `uip` command: log in once with an external application, then run the command with every input as a flag. For the general setup, refer to [Your first pipeline](./first-pipeline.md). The steps specific to a Vertical Solution follow.

### Set up the external application

1. In **Admin** > **External Applications**, create a **Confidential** application with the client credentials grant.
2. Give it the application scopes your vertical lists. Each vertical documents the scopes its deploy and its seeding need, because they depend on what the solution installs.
3. For seeding, give the application access to the folder you deploy into: in Orchestrator, go to **Tenant** > **Manage Access** > **Assign roles** > **External application**, and assign the folder role your vertical lists. Solution folders created under that folder inherit the assignment, so you do this once per target folder.
4. Store the client ID and secret as pipeline secrets.

A missing scope shows up as a `403` on the deploy step that needs it. Add the scope, log in again so the token carries it, then run `uip vss deploy resume <job-id>` to continue from that step. Without the folder role, the seed run reports that the folder shows none of the entities to this login.

If you also give the application user scopes, hold each of them as an application scope too, or the login is refused with `not allowed to access User scopes`.

Log in with the `env.` form, so the values never appear on a command line:

```bash
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT" \
  --scope "<the scopes your vertical lists>"
```

Pass `--scope` with the scopes your vertical lists, space-separated. Without it, the CLI sends no scope at all, and some application registrations refuse that login with `invalid_scope`. Setting `auth.scopes` in the CLI configuration works too. Add `--authority <url>` when the organization is not on `cloud.uipath.com`. For details, refer to [External Application (client credentials)](./authentication.md#flow-2-external-application-client-credentials).

If your pipeline already holds a token, environment-variable authentication works too, and the deploy runs as the owner of the token — a user or an external application. It needs all six variables, IDs included:

- `UIPATH_CLI_ENABLE_ENV_AUTH=true`
- `UIPATH_CLI_AUTH_TOKEN`
- `UIPATH_CLI_ORGANIZATION_NAME`
- `UIPATH_CLI_ORGANIZATION_ID`
- `UIPATH_CLI_TENANT_NAME`
- `UIPATH_CLI_TENANT_ID`

Add `UIPATH_URL` when the token is an opaque Personal Access Token, which carries no `iss` claim to derive the service URL from. Refer to [Environment-variable auth](./authentication.md#flow-4-environment-variable-auth-access-token-already-in-hand).

### Run the deploy

By default, the CLI prompts only at an interactive terminal, so in a pipeline it never blocks: a missing input becomes a structured failure that names the flag to pass. The global `--interactive` option turns prompting on regardless — `uip --interactive vss deploy` asks even with no terminal attached — so leave it off in CI. Refer to [Global options](./global-options.md).

```bash
uip vss deploy \
  --package-name <package-name> \
  --package-version 1.4.2 \
  --folder-path "Shared/Production" \
  --deployment-name my-solution-prod \
  --config <KEY>=env.MY_SECRET \
  --yes \
  --output json
```

Detach long deploys, so the pipeline does not hold a process open for the whole run:

```bash
JOB=$(uip vss deploy --package-name <package-name> --package-version 1.4.2 \
        --folder-path "Shared/Production" --yes --no-seed --no-wait --output json \
      | jq -r '.Data.JobId')

uip vss deploy status "$JOB" --output json
```

A detached job never writes the seed workspace. Once `deploy status` shows the job succeeded, pass the package and version to `deploy seed`, which downloads the templates into `./seeding/<package-name>` before it seeds. The job also reports the folder the solution installed into, which is the scope for those records:

```bash
INSTALLED_FOLDER_KEY=$(uip vss deploy status "$JOB" --output json \
      | jq -r '.Data.InstalledFolderKey')

uip vss deploy seed --package-name <package-name> --package-version 1.4.2 \
  --folder-key "$INSTALLED_FOLDER_KEY" --yes --output json
```

An upgrade or downgrade is addressed to the deployment name — refer to [Deployment name](#deployment-name). The CLI sends the name the service recorded for the deployment. Add `--deployment-name` only when that record carries no name:

```bash
uip vss deploy \
  --package-name <package-name> \
  --package-version 1.5.0 \
  --action upgrade \
  --deployment-name my-solution-prod \
  --folder-key "$PROD_FOLDER_KEY" \
  --resource-config deploy-config.json \
  --yes \
  --output json
```

`uip vss deploy` refuses an old-structure package — one whose manifest declares `dataFabric.schemaFilename` — before a job exists. For seeding such a package, refer to [`uip vss deploy seed`](./uip-vss-deploy-seed.md#which-folder-gets-seeded).

## Exit codes

| Code | `Result` | Meaning |
|---|---|---|
| `0` | `Success` | The command finished its part: the job succeeded, was submitted (`--no-wait`), or was detached (Ctrl+C). A submitted or detached job can still be running, paused, or failed, so check it with `deploy status` and continue it with `deploy resume` if needed. A cancel or resume of a job that already succeeded or was canceled also exits `0`. |
| `1` | `Failure` | A watched `deploy` or `deploy resume` ended with the job failed, paused, or canceled. Also returned when the platform refused the run: no entitlement, no capacity, a package that declares tenant-level resources, or contact lost mid-run. Ctrl+C during the submit is also a `1` (`lost-contact`), because it is not known yet whether a job exists. `deploy status` reports these states in `Data.Status` and exits `0`, as does a `deploy cancel` that goes through, so a polling step never fails for them. |
| `2` | `AuthenticationError` | No usable login. |
| `3` | `ValidationError` | A required flag is missing, or a value is not usable: a package, version, job ID, or deployment that does not exist, or a fresh-install deployment name that is already taken, when the CLI can check it. An external application refused the read of the tenant's deployments skips that check, so there a taken name is not a `3`. |
| `4` | `TimeoutError` | `--timeout` elapsed while the job was still going. The job is not canceled: it is still running, waiting at a pause nobody answered, or failed and checkpointed after a retry prompt nobody answered. A job that had already finished does not return `4`. Check `deploy status` before acting, and continue it with `deploy resume` if needed. |
| `130` | — | Ctrl+C stopped `deploy status` or `deploy cancel` before it finished. |

The line between `1` and `3` is whether another flag, or a different value in the one you passed, can fix it. A version that does not exist is a `3`. A package with no other published version is a `1`, because no flag helps until one is published.

For the exit codes shared by every command, refer to [Exit codes](./exit-codes.md).

### Failure envelopes

A `1` from a failed or paused job always carries the `deploy resume` command to run in `Instructions`.

Every failure names its reason in `Code`, for example:

- `job-paused`
- `job-failed`
- `job-canceled`
- `declined`
- `not-entitled`
- `capacity`

`Result` and `ErrorCode` are shared with every other `uip` command, so more than one reason maps to one value: a paused job and a failed one are both `Result: Failure` with `ErrorCode: unknown_error`. Only `Code` says which happened, and so whether `deploy resume` is the answer.

On success, `Code` names the response shape in PascalCase (`VerticalSolutionDeployStatus`); on failure, it names the reason in kebab-case. The pair of `Result` and `Code` is the value to branch on.

The `Retry` hint tells retryable failures apart:

| Failure | `ErrorCode` | `Retry` |
|---|---|---|
| `deploy resume`: setup pause or failed job | `unknown_error` | `RetryLater` — the same resume picks it up again. |
| `deploy`: paused or failed job | `unknown_error` | `RetryWillNotFix` |
| Pause for an expired login | `authentication_required` | `RetryWillNotFix` — run `uip login` first. |
| Service at deploy capacity | `rate_limited` | `RetryAfter10Seconds` |
| Entitlement check could not be reached | `server_error` | `RetryAfter30Seconds` |
| Any other refusal a retry cannot fix | — | `RetryWillNotFix` |

## Related

- [uip vss deploy seed](./uip-vss-deploy-seed.md) — load Data Fabric seed data after a deploy.
- [`uip login`](./uip-login.md) — credentials the deploy runs with.

## See also

- [Vertical Solutions tool overview](./uip-vss.md)
- [Authentication](./authentication.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)
