Octopus "The step failed" in CI

One named step in the deployment process ended in a Failed state. The most common source is a Run a Script step whose command returned a non-zero exit code, but any step that raises a fatal error fails here and fails the deployment.

What this error means

The task log shows "The step 'Deploy Web' failed" or "Run a Script failed", with the step exit code and the last lines of its output above.

octo

The step 'Run a Script' failed.
System.Exception: The remote script failed with exit code 1.

Common causes

A script step exited non-zero

A command inside a Run a Script step returned a non-zero exit code, which Octopus treats as a step failure by default.

A package or config step hit a fatal error

A deploy-package, config-transform, or variable-substitution step failed because a file, path, or variable was missing on the target.

How to fix it

Read the step output and fix the command

Open the failing step in the task log and read its final output lines.
Reproduce the command locally or on the target to see the real error.
Fix the script or configuration and re-run the deployment.

Handle expected non-zero exits explicitly

If a command can legitimately return non-zero, handle its exit code in the script rather than letting it fail the whole step.

PowerShell

# in a Run a Script step
if ! some-command; then
  Write-Warning "some-command returned non-zero, continuing"
fi

How to prevent it

Test deployment scripts against a staging target before Production.
Handle expected non-zero exit codes inside the script.
Keep required files and variables present on every target.