Skip to main content

Vault troubleshooting

Learn about Piiano Vault software troubleshooting, status checks, license validation, and more for hosted and self hosted instances

This guide focuses on the development edition of Vault. You usually start with this edition when running Vault for the first time.

Start with troubleshooting for your Vault type: Hosted version or Self-hosted version. Then, continue with common troubleshooting.

Hosted version of Vault

You access your vaults at
Selecting a Vault instance redirects you to a URL like this:<your dedicated Vault ID>.

Vault online status

It can take a few minutes for a vault to start after installation. While starting, the console displays the vault's state as STARTING with a yellow indicator. When ready, the color changes to green, and the state is RUNNING:

The console showing a vault as runningThe console showing a vault as running

A PAUSED state occurs when your trial has expired. Contact us to extend it. Your data isn't deleted for an additional few weeks, during which we can resume the Vault for you. After that grace period, the Vault will be irreversibly deleted.

A paused system does not respond to API calls.

The console showing a vault as pausedThe console showing a vault as paused

Verify connectivity to your Vault

When your vault is running, confirm you have connectivity from your machine using the status check.

Using the pvault CLI

With the CLI installed, copy the command from your online vault page so it includes your vault's URL:

The CLI check health command shown in a vault's status pageThe CLI check health command shown in a vault's status page

The expected response:

| data | control |
| pass | pass |
Using cURL

Copy the curl command from your online vault page so it includes your vault's URL:

The curl check health command shown in a vault's status pageThe curl check health command shown in a vault's status page

The expected response:

Troubleshooting lack of access

If you can't access your vault even though its state appears online as RUNNING, check the following:

  1. Use nslookup to check that your vault DNS resolves. It is advertised by AWS and should not take more than one minute to propagate.
  2. Check that you don't have a firewall blocking outgoing connections to TCP port 8123.
  3. Refresh your vault's page to check that it is running.

Viewing logs

View your Vault's logs online at the Audit and logs tab. If you experience errors, check the application server-side logs. Selecting the audit logs option is useful for troubleshooting access errors to resources.

Self-hosted version of Vault

The following steps refer to the pvault-dev version, which includes Vault and an embedded database.

Verify Vault is running

Verify the Vault container is running with docker ps. The output should be similar to:

CONTAINER ID   IMAGE                     COMMAND                  CREATED         STATUS         PORTS                                            NAMES
6d716d8954b7 piiano/pvault-dev:1.11.3 "/usr/local/bin/pvau…" 6 seconds ago Up 5 seconds>5432/tcp,>8123/tcp pvault-dev

When Vault completes initialization, the last message should be similar to this one (registration_uid redacted). The message appears on the console where the docker run is executing:

{"level":"info","type":"log","version":"","product":"vault","service":"pvault-dev","customer_identifier":"unset","customer_env":"unset","dev_mode":true,"backing_store":"psql","deployment_mode":"container","worker_id":"237446792663609344","registration_uid":"email|xxxxxxxxxxxxxxxxxxxxxxxx","operation_id":"internal","vault_id":"237446797700968448","time":1697610528699,"caller":"","message":"Server is up and running. Serving HTTP on"}

If you don't get confirmation that the server is up and running:

  1. Verify you correctly copied the docker run command from the get started guide. You must have a valid license key. You can obtain one by registering from the get started page.
  2. Verify your system complies with the basic system requirements.
  3. Check that Docker is running. We recommend using Docker Desktop on personal machines.
  4. Ensure the Vault port 8123 is available. Check this using: netstat -anl | grep -i listen | grep 8123.

Verify connectivity to the Vault

Using the pvault CLI

With the CLI installed, run:

pvault status

If Vault is running, you see:

| data | control |
| pass | pass |
Using cURL

Check the health endpoint on control and data. In most deployment options, they are served by the same container:

> curl http://localhost:8123/api/pvlt/1.0/ctl/info/health

> curl http://localhost:8123/api/pvlt/1.0/data/info/health

Calls to health do not appear on the Vault logs by default.

Viewing logs

View your Vault logs by following these instructions.

Common troubleshooting

Ensure version compatibility

These instructions use the Vault CLI. Alternatively, use curl or run queries from the API page of your Vault. The self-hosted API page is located at http://localhost:8123/docs/api. For hosted vaults, add the relative path /docs/api to your vault's URL.

To identify the CLI and server versions, run:

> pvault version
| vault_id | vault_version | cli_version | db_schema_version |
| 237446797700968448 | | v1.9.0-1-ge2a380b2a | 20231001125049 |

It is important you run the same CLI version as the server. If needed, download a previous CLI version and do not use the latest.

Check your license

Check your license with:

pvault admin get-license
| expiration | key |
| Mon, 16 Oct 2023 06:53:17 UTC | ...F_qdfk2euqNUmzBg |

If your license has expired, obtain a new license online or contact Piiano for a long-term license. Then, apply the new license or consult the reference:

PVAULT_SERVICE_LICENSE="<copy the new license here>"
pvault admin set-license --key $PVAULT_SERVICE_LICENSE
INF Command completed successfully