--- title: "Troubleshooting" manual: "Secrets Vault" version: "1.2" permalink: "https://docs.typo3.org/permalink/netresearch/nr-vault:troubleshooting@1.2" source: "Troubleshooting/Index.rst" rendered: "2026-10-31T22:33:18+00:00" --- # Troubleshooting {#troubleshooting} Common issues and frequently asked questions about nr-vault. ## FAQ {#troubleshooting-faq} ### I lost the master key. Can I recover my secrets? {#troubleshooting-lost-master-key} 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.2) for storage recommendations. ### Users get "Access denied" when reading secrets {#troubleshooting-access-denied} Check the following: 1. **Operation and per-secret access**: Verify the required `tx_nrvault:*` group permission and the secret ownership or read/write group grants. An operation grant alone does not grant access to every secret. Check group membership in **Backend Users**. 1. **Field restrictions**: For TCA vault fields, also check Page or User TSconfig under `vault.permissions` (`reveal`, `copy`, `edit` and `readOnly`). These field controls do not replace the vault ACL. 1. **Administrator access**: Administrators normally bypass vault ACL checks. In the hardened profile with `disableAdminOverride` enabled, they need operation and per-secret grants too, unless an audited break-glass session is active. 1. **CLI access**: CLI commands require explicit configuration. See [Configuration](https://docs.typo3.org/permalink/netresearch/nr-vault:configuration@1.2) for details. ### Can I use nr-vault without Composer? {#troubleshooting-non-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 {#troubleshooting-decryption-failed} 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 {#troubleshooting-master-key-not-found} 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`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Configuration/Typo3ConfVars/Index.html#file-project-config-system-settings-php). ### Performance with many secrets {#troubleshooting-performance} 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.2)). 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 {#troubleshooting-rotate-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 {#troubleshooting-migrate-plaintext} 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.2) 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 ```