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 sandbox.app.piiano.io/vaults.
Selecting a Vault instance redirects you to a URL like this: https://sandbox.app.piiano.io/vaults/<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:
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.
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 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 expected response:
{"status":"pass"}
Troubleshooting lack of access
If you can't access your vault even though its state appears online as RUNNING, check the following:
- Use
nslookupto check that your vault DNS resolves. It is advertised by AWS and should not take more than one minute to propagate. - Check that you don't have a firewall blocking outgoing connections to TCP port 8123.
- 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.1 "/usr/local/bin/pvau…" 6 seconds ago Up 5 seconds 0.0.0.0:5432->5432/tcp, 0.0.0.0:8123->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":"1.9.0.1-ge2a380b2a","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":"github.com/piiano/vault/common/server/runner.go:85","message":"Server is up and running. Serving HTTP on 0.0.0.0:8123"}
If you don't get confirmation that the server is up and running:
- Verify you correctly copied the
docker runcommand from the get started guide. You must have a valid license key. You can obtain one by registering from the get started page. - Verify your system complies with the basic system requirements.
- Check that Docker is running. We recommend using Docker Desktop on personal machines.
- 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
{"status":"pass"}
> curl http://localhost:8123/api/pvlt/1.0/data/info/health
{"status":"pass"}
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 | 1.9.0.1-ge2a380b2a | 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