> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-integration/troubleshooting-and-resources/troubleshoot-harness-ci/debug-mode.md).

# Debug with SSH

{% hint style="info" %}
This is an early access feature and is behind the feature flag `CI_REMOTE_DEBUG`. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
{% endhint %}

You can use the Harness CI **Re-run in Debug Mode** feature to quickly and securely troubleshoot remote builds by SSH-ing into a debug session on the build's remote host. With debug mode, you:

* Get temporary, secure access to the build environment without the need for permanent permission changes.
* Troubleshoot directly in the build environment, not a recreation on your local machine.
* Troubleshoot in real time, rather than waiting for logs to output after each build.

You can also use **Re-run in Debug Mode** to troubleshoot local builds.

{% embed url="<https://www.youtube.com/watch?v=HcSYidJSvK8>" %}

### Debug mode requirements <a href="#debug-mode-requirements" id="debug-mode-requirements"></a>

{% hint style="info" %}
Debug mode is available if the following conditions are met:

* You have the feature flag `CI_REMOTE_DEBUG` enabled. Contact [Harness Support](mailto:support@harness.io) to enable this feature.
* The build fails at a [Run step](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md) with a Bash, Shell, Python, or PowerShell Core (`pwsh`) script in a **Build** (`CI`) stage.
* The build runs on Linux or macOS [build infrastructures](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/which-build-infrastructure-is-right-for-me.md). Windows is not currently supported.

Debug mode is never available for a pipeline's first build. You must run the pipeline at least once before you can run the build in debug mode.
{% endhint %}

If debug mode isn't available for your pipeline, you might consider using [Harness AI](/continuous-integration/troubleshooting-and-resources/troubleshoot-harness-ci/ai.md).

### Enable debug mode <a href="#enable-debug-mode" id="enable-debug-mode"></a>

{% tabs %}
{% tab title="Remote builds" %}
If your build meets the [debug mode requirements](#debug-mode-requirements), use these steps to use debug mode for builds on Harness Cloud, self-managed VM, or Kubernetes cluster build infrastructures.

1. Create a [Harness API key and token](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md) with `pipeline execution` permissions. You must have pipeline execution permissions at the [account scope](/harness-ai/use-harness-platform/platform-access-control.md#permissions-hierarchy-scopes) in order for the token to have those permissions.
2. Navigate to the [**Builds**](/continuous-integration/use-harness-ci/use-harness-ci/viewing-builds.md), **Executions**, or **Execution History** page.
3. Locate the build you want to troubleshoot, select **More Options** (⋮), and select **Re-run in Debug Mode**.

   <figure><img src="/files/DM23Eu0cSSWFR6lyQjMc" alt=""><figcaption></figcaption></figure>
4. Wait while the build runs. If the Run step fails, the build stops and generates log output with an SSH command you can use to SSH into the session on the remote host.

   The SSH command is formatted as follows. Replace `{harness pat}` with your [token](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md) that has `pipeline execution` permissions.

   ```
   ssh {harness pat}:<your-harness-account-ID>:<random-session-token>@tmate.harness.io
   ```

   <figure><img src="/files/0oxRKPp5nRjHeVWH0Ih2" alt=""><figcaption></figcaption></figure>
5. While in the debug session, use the CLI to reproduce and troubleshoot the issue on the remote host.
6. To terminate the debug session, abort the build, and then run a new build to determine if the issue is resolved. Sessions automatically terminate after one hour or at the step timeout limit, whichever occurs first.
   {% endtab %}

{% tab title="Local builds" %}
If your build meets the [debug mode requirements](#debug-mode-requirements), use these steps to use debug mode for builds on [local runner build infrastructures](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure.md).

1. [Download and install tmate](https://github.com/harness/tmate/releases/download/1.0/tmate-1.0-static-linux-amd64.tar.xz) on the runner's host machine.
2. If necessary, mount the install path. By default, Harness mounts the `/addon` path. If you installed tmate elsewhere, you need to mount that path.
3. In your CI pipeline, add the environment variable `TMATE_PATH` to your Run step. Set the value to the tmate mount path, such as `/addon/tmate`.
4. Create a [Harness API key and token](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md) with `pipeline execution` permissions. You must have pipeline execution permissions at the [account scope](/harness-ai/use-harness-platform/platform-access-control.md#permissions-hierarchy-scopes) in order for the token to have those permissions.
5. Navigate to the [**Builds**](/continuous-integration/use-harness-ci/use-harness-ci/viewing-builds.md), **Executions**, or **Execution History** page.
6. Locate the build you want to troubleshoot, select **More Options** (⋮), and select **Re-run in Debug Mode**.

   <figure><img src="/files/DM23Eu0cSSWFR6lyQjMc" alt=""><figcaption></figcaption></figure>
7. Wait while the build runs. If the Run step fails, the build stops and generates log output with an SSH command you can use to SSH into the debug session.

   The SSH command is formatted as follows. Replace `{harness pat}` with your [token](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md) that has `pipeline execution` permissions.

   ```
   ssh {harness pat}:<your-harness-account-ID>:<random-session-token>@tmate.harness.io
   ```

   <figure><img src="/files/0oxRKPp5nRjHeVWH0Ih2" alt=""><figcaption></figcaption></figure>
8. While in the debug session, use the CLI to reproduce and troubleshoot the issue.
9. To terminate the debug session, abort the build, and then run a new build to determine if the issue is resolved. Sessions automatically terminate after one hour or at the step timeout limit, whichever occurs first.
   {% endtab %}
   {% endtabs %}

{% hint style="info" %}
You can force a build to fail if you need to troubleshoot pipelines that appear to build successfully but still need remote troubleshooting. To do this, add a [Run step](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md) with the command `exit 1`. This forces the build to fail so you can re-run it in debug mode.
{% endhint %}