> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/p0-cli/troubleshooting/p0-ssh.md).

# p0 ssh

### 1. Quick health checklist <a href="#id-1-quick-health-checklist" id="id-1-quick-health-checklist"></a>

| Check                  | Command                                                                                                                      | Why it matters                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Node ≥ 22              | `node -v`                                                                                                                    | Older Node versions break npm‑installed CLI binaries. |
| P0 CLI in PATH         | `p0 --version`                                                                                                               | Verifies global install succeeded.                    |
| AWS CLI v2             | `aws --version`                                                                                                              | `ssm start-session` lives here.                       |
| Session Manager plugin | `session-manager-plugin --version`                                                                                           | Required for SSM tunnel on AWS.                       |
| gcloud SDK             | `gcloud --version`                                                                                                           | Provides `start-iap-tunnel`.                          |
| gcloud login           | `gcloud auth list`                                                                                                           | IAP tunnel fails without a valid OAuth token.         |
| P0 identity file       | <p>macOS & Linux:<br><code>cat \~/.p0/identity.json</code><br>Windows:</p><p><code>%USERPROFILE%.p0\identity.json</code></p> | Confirms `p0 login` completed & org slug recorded.    |

***

### 2. Common CLI start‑up errors <a href="#id-2-common-cli-start-up-errors" id="id-2-common-cli-start-up-errors"></a>

| Symptom / Message                                  | Likely cause                                    | Fix & rationale                                                                      |
| -------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
| `node: bad option: --require ts-node/register`     | Node < 22.                                      | Upgrade Node: the CLI is compiled for ESM features included in v22+.                 |
| `Cannot find module '@p0security/cli'`             | CLI not in PATH or NPM global root not in PATH. | Re‑install with `npm i -g @p0security/cli` **and** restart terminal so PATH reloads. |
| `The 'org' argument is required` during `p0 login` | Forgot org slug env var.                        | Run `p0 login <ORG_ID>` or export `P0_ORG`.                                          |

***

### 3 Errors *before* cloud access is granted (P0 layer) <a href="#id-3-errors-before-cloud-access-is-granted" id="id-3-errors-before-cloud-access-is-granted"></a>

| Message                                                             | Cause                                             | Fix                                                                      |
| ------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| `This organization is not configured for SSH access via the P0 CLI` | Admins haven't installed the **SSH integration**. | Ask platform team to complete P0 onboarding for SSH providers.           |
| `Server did not return a request id`                                | Backend 503 or mis‑shaped request.                | Retry. If persistent, grab CLI logs (`--debug`) and open support ticket. |
| `--approved` exits immediately                                      | Access not pre‑approved.                          | Remove the flag **or** get an approver to pre‑approve via Slack.         |

***

### 4 Errors during *access propagation* (AWS & GCP) <a href="#id-4-errors-during-access-propagation" id="id-4-errors-during-access-propagation"></a>

| Cloud | Error                                                                      | Root reason                                 | Resolution                                                                                                                                 |
| ----- | -------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| AWS   | `AccessDeniedException` OR `is not authorized to perform ssm:StartSession` | IAM policy not yet visible to SSM agent.    | Wait – CLI retries 8 min by default. Use `--debug` to watch attempts.                                                                      |
| AWS   | `Unable to locate credentials…` inside ProxyCommand                        | Local **AWS CLI** lacks auth (SSO or keys). | `aws sso login --profile <name>`**or** set `AWS_PROFILE`.                                                                                  |
| GCP   | `Please log in to the gcloud CLI to SSH`                                   | OAuth token expired.                        | The CLI re-runs `gcloud auth login` automatically; complete the prompt. If it persists, run `gcloud auth login` manually (token TTL 12 h). |
| GCP   | Tunnel hangs at 127.0.0.1:0                                                | Firewall denies egress websockets.          | Check corporate proxy, allow `iap.googleapis.com:443`.                                                                                     |

***

### 5 OpenSSH / Network level failures **after** access granted <a href="#id-5-openssh-network-level-failures-after-access-granted" id="id-5-openssh-network-level-failures-after-access-granted"></a>

| Error / Symptom                                            | Cause                                               | Fix                                                                                               |
| ---------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ssh: connect to host … port 22: Connection refused` (GCP) | SSH daemon disabled or moved.                       | Start `sshd` on VM or revert to port 22. (Azure note: port override unsupported.)                 |
| `Too many authentication failures`                         | Agent offered multiple keys before the P0 temp key. | CLI already adds `IdentitiesOnly=yes`; override your local `ssh_config` or kill `ssh-agent` keys. |
| Port forward fails with `bind: Address already in use`     | Local port occupied.                                | Change **local** part of `-L` or `-R` binding.                                                    |
| Windows PowerShell: arguments split incorrectly            | Quotes not escaped.                                 | Wrap the entire SSH tail in double quotes and escape inner quotes (see examples).                 |

***

### 6 Sudo & privilege issues <a href="#id-6-sudo-and-privilege-issues" id="id-6-sudo-and-privilege-issues"></a>

| Scenario                 | Explanation                                                  | Mitigation                                                       |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------- |
| `sudo: no tty present`   | Your remote command used `sudo` inside non‑interactive mode. | Transpose with `sudo -n <cmd>` **or** request interactive shell. |
| No sudo despite `--sudo` | Approver rejected elevated scope.                            | Check Slack thread, re‑submit with business justification.       |

***

### 7 File‑transfer (SCP) issues <a href="#id-7-file-transfer-scp-issues" id="id-7-file-transfer-scp-issues"></a>

| Error                                | Root cause                             | Fix                                                                            |
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------ |
| `scp: protocol error: : Broken pipe` | ProxyCommand died (SSM/IAP restarted). | Large transfers: add `-- -o ServerAliveInterval=60` flag to keep tunnel alive. |

***

### 8 Collecting diagnostics <a href="#id-8-collecting-diagnostics" id="id-8-collecting-diagnostics"></a>

Run with maximum verbosity and pipe logs:

```plaintext
P0_LOG_LEVEL=debug p0 ssh <dest> --provider <cloud> --debug -- -vvv 2>&1 | tee p0-debug.log
```

Upload `p0-debug.log` in your support ticket. It includes:

* CLI version, Node version, OS.
* Full child commands (AWS, gcloud, ssh).
* SSH handshake at `-vvv` level.

**Privacy note:** The log contains temporary instance IDs and IPs but never the private key material.

***

### 9 Escalate to support <a href="#id-9-escalate-to-support" id="id-9-escalate-to-support"></a>

Gather the following:

1. **Command you ran** (with flags).
2. **Terminal output** (see [Collecting diagnostics](#8-collecting-diagnostics)).
3. Approximate **UTC timestamp**.
4. **Org slug** and **request ID** (shown in Slack).

Send to <support@p0.dev> or post in **#p0-community** Slack.

***

### 10 Self‑service updates & docs <a href="#id-10-self-service-updates-and-docs" id="id-10-self-service-updates-and-docs"></a>

* **Release notes:** <https://github.com/p0-security/p0cli/releases>
* **Full docs:** <https://docs.p0.dev>
* **Upgrade CLI:** `npm -g update @p0security/cli`

***

### 11 Appendix – Decision tree (plain text) <a href="#id-11-appendix-decision-tree" id="id-11-appendix-decision-tree"></a>

```plaintext
Start
 ├─ Does `p0` command run at all? ── No → Check Node + npm global install.
 │
 ├─ Does CLI create Permission Request? ── No → Check org slug, login, or network.
 │
 ├─ Waiting >8 min at "propagate"? ── Yes → Cloud IAM/OS Login stuck; contact admin.
 │
 ├─ Does SSH handshake start? ── No → ProxyCommand dependency (AWS CLI, gcloud) fails.
 │
 ├─ Shell opens but command fails? ── Yes → Remote OS issue (sshd, sudo), fix on VM.
 │
 └─ Success
```

***

If these steps do not resolve your issue, contact <support@p0.dev> with the diagnostics from section 8.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.p0.dev/p0-cli/troubleshooting/p0-ssh.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.