---
title: "Troubleshooting"
manual: "nr-vault"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-vault:troubleshooting@1.0"
source: "Troubleshooting/Index.rst"
rendered: "2026-09-18T07:37:50+00:00"
---

# Troubleshooting {#troubleshooting-1}

Common issues and frequently asked questions about nr-vault.

## FAQ {#faq}

### I lost the master key. Can I recover my secrets? {#i-lost-the-master-key-can-i-recover-my-secrets}

No. This is by design. The master key is the root of trust for all
encrypted secrets. Without it, decryption is impossible.

**What to do:**

1.  Restore the master key from a backup if available.
1.  If no backup exists, all secrets encrypted with that key are
    permanently lost.
1.  Generate a new master key and re-encrypt all secrets from their
    original plaintext sources.

> [!TIP]
> Always keep a secure, offline backup of your master key. See
> [File storage recommendations](https://docs.typo3.org/permalink/netresearch/nr-vault:security-file-storage@1.0) for storage recommendations.

### Users get "Access denied" when reading secrets {#users-get-access-denied-when-reading-secrets}

Check the following:

1.  **Backend user group**: The user must belong to a group that has
    access to the secret. Verify group membership in
    **Backend Users** module.
1.  **TSconfig restrictions**: Check if Page TSconfig or User TSconfig
    restricts access to vault features. Look for
    `tx_vault.` prefixed settings.
1.  **Ownership**: Only the secret creator and members of allowed groups
    can access a secret. Administrators can access all secrets.
1.  **CLI access**: CLI commands require explicit configuration. See
    [Configuration](https://docs.typo3.org/permalink/netresearch/nr-vault:configuration@1.0) for details.

### Can I use nr-vault without Composer? {#can-i-use-nr-vault-without-composer}

No. nr-vault requires a Composer-based TYPO3 installation. Classic
(non-Composer) installations are not supported. This is because nr-vault
depends on packages (such as `sodium`) that must be managed through
Composer's autoloader.

If you are using a classic installation, migrate to Composer first. See
the [TYPO3 documentation on Composer migration](https://docs.typo3.org/m/typo3/guide-installation/main/en-us/MigrateToComposer/Index.html).

### "Decryption failed" error {#decryption-failed-error}

This error occurs when the encrypted data cannot be decrypted. Common
causes:

-   ****Key mismatch****

    The master key currently configured does not match the key used to
    encrypt the secret. This happens when:

    -   The master key file was replaced or regenerated.
    -   The environment variable points to a different key.
    -   You restored a database backup but not the corresponding master key.

-   ****Corrupted data****

    The encrypted value in the database has been modified or truncated.
    This can happen due to:

    -   Incomplete database migrations.
    -   Manual edits to the database.
    -   Character encoding issues during database import/export.

**Resolution:**

1.  Verify that the active master key matches the one used during
    encryption.
1.  Check database integrity for the `tx_nrvault_secret` table.
1.  If the data is corrupt, restore from a database backup and ensure
    the matching master key is in place.

### "Master key not found" error {#master-key-not-found-error}

This means nr-vault cannot locate or read the master key from the
configured provider.

**File provider:**

-   Verify the key file exists at the configured path.
-   Check file permissions: the web server user must be able to read the
    file (recommended: `0400`).
-   Ensure the path is absolute, not relative.

**Environment provider:**

-   Verify the environment variable is set:
    `echo $NR_VAULT_MASTER_KEY`.
-   Check that the variable is available to the PHP process (not just
    the shell). For Apache, use `SetEnv`; for PHP-FPM, use
    `env[NR_VAULT_MASTER_KEY]` in the pool configuration.
-   In containerized environments, ensure the variable is passed through
    `docker-compose.yml` or the orchestrator's secret injection.

**TYPO3 provider (default):**

-   Ensure `$GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey']` is
    set in `settings.php`.

### Performance with many secrets {#performance-with-many-secrets}

If you manage a large number of secrets, consider these optimizations:

-   ****Batch loading****

    Use the `VaultService::list()` method with context filters
    rather than loading all secrets at once. The service optimizes
    queries when a context is specified.

-   ****Caching****

    Decrypted values are **not** cached — not across requests and not
    within one. Every `retrieve()` decrypts again and writes its own
    audit row, which is what makes the audit trail a record of actual
    access rather than of cache misses. Do not add a plaintext cache in
    your own application layer either: it silently removes both the
    per-read access check and the audit entry.

    What *is* cached is the master key, for the lifetime of a request that
    touches a secret ([ADR-020: Master key request-lifetime caching](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-020-master-key-request-lifetime-caching@1.0)).
    Long-running processes should call
    `MasterKeyProviderInterface::clearCachedKey()` to bound its
    residency.

-   ****Database indexing****

    The `tx_nrvault_secret` table includes indexes on commonly queried
    columns. Ensure these indexes exist after migrations.

### How to rotate the master key {#how-to-rotate-the-master-key}

Master key rotation re-encrypts all Data Encryption Keys (DEKs) with a
new master key without changing the actual secret values.

1.  **Create a backup** of the current master key and database.
1.  **Generate a new master key.** The file master-key provider accepts either
    32 raw bytes or a base64-encoded 32-byte key. A base64 key file is easy to
    create with:

    ```bash
    openssl rand -base64 32 > /secure/path/new-master-key
    ```

    (`vault:init` itself writes a raw 32-byte key file by default, or a
    base64 value with `--env`; the file provider reads both.)
1.  **Run the rotation command** with `--confirm` (without it the command
    prints an opt-in warning and exits without rotating):

    ```bash
    vendor/bin/typo3 vault:rotate-master-key \
        --new-key=/secure/path/new-master-key \
        --confirm
    ```

    Use `--dry-run` first to simulate, and `--old-key` if the current key
    cannot be auto-detected from your provider configuration.
1.  **Update your configuration** to point to the new master key.
1.  **Verify** that secrets are still readable.
1.  **Securely delete** the old master key after confirming success.

> [!WARNING]
> Do not delete the old master key until you have verified that all
> secrets decrypt correctly with the new key.

### How to migrate from plaintext to vault {#how-to-migrate-from-plaintext-to-vault}

To migrate existing plaintext credentials stored in TYPO3 records to
vault-managed secrets:

1.  **Identify fields** that contain plaintext secrets (API keys,
    passwords, tokens).
1.  **Add TCA configuration** for those fields using the
    `vaultSecret` renderType. See [Developer](https://docs.typo3.org/permalink/netresearch/nr-vault:developer@1.0) for TCA
    integration details.
1.  **Run the migration command:**

    ```bash
    vendor/bin/typo3 vault:migrate-field \
        tx_myext_domain_model_connection \
        api_key
    ```

    This reads the current plaintext value, encrypts it into the vault,
    and replaces the field value with a vault reference identifier.
1.  **Verify** that the application still reads the credentials
    correctly through the vault API.
1.  **Clear caches** after migration:

    ```bash
    vendor/bin/typo3 cache:flush
    ```