Guides
SupportStatusSign UpLogin

Reporting KMS Errors

Suggest Edits

Most questions and issues with KMS are addressed in this article.

If you have additional questions or issues, follow these steps before submitting a support request.

Required Information

  1. Verify Your KMS Version

    • Ensure you have installed the latest KMS version.
    • Check the latest version of Tatum KMS HERE.

  2. Generate a Debugging Report

    • Use the report command to generate a detailed system report. This report includes:
      • Your KMS version
      • Node.js version
      • Signature_ID storage type general details (Mnemonic or PrivateKey-based).
      • Any warnings identified

    Example request:

       $ tatum-kms e3015fc0-2112-4c8a-b8bf-353b86f63ba5,11115fc0-2112-4c8a-b8bf-353b86f63111
   {
     "system": {
       "kmsVersion": "7.0.6",
       "nodeVersion": "v18.18.2",
       "store": {
         "type": "LOCAL",
         "exists": true
       }
     },
     "wallets": {
       "e3015fc0-2112-4c8a-b8bf-353b86f63ba5": {
         "type": "PRIVATE_KEY",
         "chain": "BTC",
         "testnet": true
       },
       "11115fc0-2112-4c8a-b8bf-353b86f63111": {
         "type": "MNEMONIC",
         "chain": "ETH",
         "testnet": true,
         "warnings": [
           "No xpub found"
         ]
       }
     },
     "apiKey": "t-6111***************************************222222",
     "warnings": [
       "Wallets file is not accessible"
     ]
   }

  3. Explore Additional Resources

🚧

Attention

  • Tickets submitted without the KMS report file will be rejected.
  • Submissions with a KMS version older than the current version will also be rejected.

Why This Information Matters

Providing a KMS report, error details, and current version information allows us to identify potential misconfigurations or compatibility issues. Without this data, troubleshooting may be significantly delayed or unfeasible.

  • Outdated versions may not include recent bug fixes or security updates.
  • The KMS report gives a snapshot of your system setup, helping us diagnose potential issues quickly.
  • Security-related concerns often require specific details to ensure compliance with best practices.

By following this guide, you help us resolve your issue as efficiently as possible.

Disclaimer

By using KMS, it is assumed that you, the User, have extensive blockchain knowledge and are an experienced developer.

  1. Key Security Facts
    • Tatum does not store PrivateKeys or Mnemonics.
    • KMS is a self-custodial solution where Tatum does not have access to the user's KMS, by design.
    • Wallet storage is encrypted with an AES cipher and stored on your local server. You must enter your password to unlock wallet storage.
      • The password encrypts Mnemonics and PrivateKeys inside the wallet storage file.
      • The default wallet storage file name is wallet.dat.
  2. Why Tatum Cannot Troubleshoot Signed Transactions
    • Transactions signed via KMS bypass Tatum’s logs and are directly broadcast to the blockchain.
    • If a malformed transaction is sent for signing, it may still return a "successful" response from Tatum's API or SDK, as Tatum does not log payloads of "successful" HTTP 200 requests.
    • If the blockchain rejects the transaction, the error message will be returned to your KMS instance, not to Tatum.

❗️

Warning

Keeping track of logs: You must keep track of the original request logs, including the payload, if you expect Tatum to assist with troubleshooting failed transactions.

Critical Warnings

  1. Losing wallet.dat can be catastrophic
    The security and storage of wallet.dat are solely your responsibility. If this file is lost or becomes irrecoverable:
    • You will lose access to your Mnemonics and PrivateKeys.
    • Tatum cannot help you recover your assets.
  2. Losing your KMS password means permanent loss
    If you lose your KMS password, you will permanently lose access to all Mnemonics and PrivateKeys stored in wallet.dat.
    • Tatum does not store or recover passwords.
    • Tatum cannot help recover lost access to encrypted wallet files.

🚧

Attention

We encourage users to take necessary precautions to back up their data securely.

Updated 19 days ago