> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs.itential.com/itential-platform/6/llms.txt
> - 2023.2: https://docs.itential.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Monitor and troubleshoot HashiCorp Vault

> Resolve common HashiCorp Vault integration issues

on-prem only

## Monitor health

Track Vault integration status:

Check the `/health/status` endpoint for Vault connectivity status.

Review Platform logs for Vault connection errors.

Set up alerts for Vault connection failures.

## Troubleshoot common issues

### Connection failures

**Symptoms:** Platform cannot retrieve secrets, authentication errors in logs.

**Solutions:**

#### Verify the Vault URL

Confirm the `vault_url` value is correct, reachable from the Platform server, and includes the correct port (default: `8200`).

#### Check Vault server status

Verify that Vault is running and unsealed. A sealed Vault returns errors for all requests.

```bash
vault status
```

Look for `Sealed: false` in the output.

#### Confirm authentication credentials

For token auth, verify that the token file exists and contains a valid, non-expired token:

```bash
cat /opt/vault/token.txt
vault token lookup <token>
```

For AppRole auth, verify the `role_id` and `secret_id` are correct and the secret\_id has not expired.

#### Check network connectivity

Confirm that the Platform server can reach the Vault server:

```bash
curl -s https://vault.company.com:8200/v1/sys/health
```

A healthy Vault returns HTTP 200.

#### Review Platform logs

Check Platform logs for specific error messages:

```bash
# Platform 6
sudo journalctl -u itential-platform -f | grep -i vault

# Platform 2023.2
sudo journalctl -u automation-platform -f | grep -i vault
```

### TLS certificate errors

**Symptoms:** Platform logs contain `UNABLE_TO_VERIFY_LEAF_SIGNATURE`.

**Cause:** Platform cannot verify the SSL certificate chain presented by the Vault server.

**Solution:** Add the Vault certificate chain to Itential Platform on every Platform server in your environment.

#### Create a certificate file

```bash
touch /tmp/vault.cert
```

#### Copy the Vault certificate chain into the file

Copy the contents of all SSL certificates in the chain in order: end-user certificate first, then intermediate certificates, then the root certificate.

```
-----BEGIN CERTIFICATE-----
<Content of end-user certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Content of intermediate certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Content of root certificate>
-----END CERTIFICATE-----
```

To retrieve the certificate chain directly from the Vault server:

```bash
openssl s_client -showcerts -connect vault.company.com:8200 </dev/null
```

#### Move the file to the certificates directory

```bash
sudo mv /tmp/vault.cert /etc/pki/tls/certs/vault.cert
```

#### Set file ownership and permissions

```bash
sudo chown itential:itential /etc/pki/tls/certs/vault.cert
sudo chmod 400 /etc/pki/tls/certs/vault.cert
```

#### Add the NODE\_EXTRA\_CA\_CERTS environment variable to the Platform service file

Find the Platform service file path:

```bash
systemctl status itential-platform
```

Edit the service file and add this line in the `[Service]` section:

```
Environment="NODE_EXTRA_CA_CERTS=/etc/pki/tls/certs/vault.cert"
```

#### Reload the daemon and restart Platform

```bash
sudo systemctl daemon-reload
sudo systemctl restart itential-platform
```

> **Info**
>
> When Vault certificates are rotated, update `/etc/pki/tls/certs/vault.cert` with the new chain, then restart Platform.

### Secret not found

**Symptoms:** Platform cannot retrieve a specific secret; adapter or integration fails to start.

**Solutions:**

#### Verify the secret reference format

Confirm the reference uses the correct syntax with a space between the path and key directives:

```
$SECRET_<path> $KEY_<key-name>
```

Common mistake: missing the space before `$KEY_`.

#### Verify the Vault path

Confirm the secret exists at the specified path in Vault. The path in a `$SECRET` reference is relative to the kv-v2 mount point and does not include `/data/`.

```bash
vault kv get <mount-point>/<path>
```

#### Confirm the secrets endpoint configuration

The `vault_secrets_endpoint` value must end with `/data`. For example, if the kv-v2 engine is mounted at `kv-v2`, the endpoint must be `kv-v2/data`.

#### Check Vault token permissions

Confirm the Vault token or AppRole has a policy that grants read access to the secret path:

```bash
vault token capabilities <token> <mount>/<path>
```

### Token expiration

**Symptoms:** Vault integration stops working after a period of time.

**Solutions:**

#### Check token TTL

```bash
vault token lookup <token>
```

Look for `expire_time` in the output.

#### Renew or replace the token

Renew the token if it is still valid:

```bash
vault token renew <token>
```

If the token has expired, generate a new one and update the token file at the path configured in `vault_token`. Restart Itential Platform after replacing the token.

#### Consider using AppRole authentication

AppRole authentication with a periodically-renewed `secret_id` is better suited for long-running production deployments than static tokens. See [Connect Platform to HashiCorp Vault](/itential-platform/secrets/hashicorp/connect) for AppRole configuration details.

## What's next

#### [Connect Platform](/itential-platform/secrets/hashicorp/connect)

Review your Vault connection settings.

#### [Use secrets](/itential-platform/secrets/hashicorp/use)

Reference Vault secrets in your configurations.