Skip to main content
This page covers the most common errors you may encounter when using encryptd, whether you’re running the secure-env CLI or calling config() in your application. Each section describes what triggers the error and the steps to resolve it.

​
[SrcIndex] ENV_PASSPHRASE not set

Full message: [SrcIndex] ENV_PASSPHRASE not set. Pass it via options.passphrase or ENV_PASSPHRASE env var. Cause: You called secure-env or config() without providing a passphrase. encryptd looks for it in two places the options.passphrase argument passed to config(), and the ENV_PASSPHRASE environment variable and found neither. Fix: Either export the variable in your shell before running any command, pass it inline, or supply it directly through the config() API:
Never hard-code your passphrase in source code or commit it to version control. Use a secrets manager, a secret variable in your deployment environment, or a .env file that is listed in .gitignore.

​
[SrcIndex] Encrypted env file not found

Full message: [SrcIndex] Encrypted env file not found at <path> Cause: encryptd looked for the .env.enc file at the given path and could not find it. This usually happens when the CLI is run from the wrong working directory or when a custom path option points to a non-existent file. Fix: Confirm the file exists and that you are in the correct directory, then pass the explicit path if needed:
Terminal
Explicit path via config()
By default, encryptd looks for .env.enc in the current working directory. If your project structure places the file in a subdirectory, you must provide the path explicitly.

​
[SrcIndex] Invalid encrypted env file. Expected valid JSON.

Full message: [SrcIndex] Invalid encrypted env file at <path>. Expected valid JSON. Cause: The file at the given path exists but is not a valid .env.enc file produced by encryptd. Common reasons include pointing at the original .env instead of .env.enc, manually editing the .env.enc file and breaking its JSON structure, or file corruption during a copy or transfer. Fix: Make sure the path you provide is the output of secure-env encrypt, not the plaintext .env. A valid .env.enc file is a JSON object containing salt, iv, content, and tag fields:
.env.enc structure
If the file is corrupted, re-encrypt from the original .env source.

​
[RustLib] Decryption failed. Wrong key or tampered file.

Full message: [RustLib] Decryption failed. Wrong key or tampered file. <error> Cause: The passphrase provided for decryption does not match the one used during encryption, or the .env.enc file has been modified since it was created. Fix: Verify that ENV_PASSPHRASE is set to exactly the same value that was used when you ran secure-env encrypt. Passphrases are case-sensitive and whitespace-sensitive. If you are certain the passphrase is correct but still see this error, the file may have been accidentally edited re-encrypt from the original .env:
Terminal
If you no longer have the original .env and the passphrase is lost, the encrypted data cannot be recovered. AES-256-GCM provides no backdoor.

​
[RustLib] Invalid salt hex / Invalid IV hex / Invalid content hex / Invalid tag hex

Full messages:
  • [RustLib] Invalid salt hex: <error>
  • [RustLib] Invalid IV hex: <error>
  • [RustLib] Invalid content hex: <error>
  • [RustLib] Invalid tag hex: <error>
Cause: One or more of the hex-encoded fields inside the .env.enc JSON (salt, iv, content, or tag) contain characters that are not valid hexadecimal. This typically happens when the file has been manually edited or partially corrupted. Fix: Do not edit .env.enc by hand. If the file has been modified, re-encrypt from the original .env:
Terminal

​
[RustLib] Invalid UTF-8

Full message: [RustLib] Invalid UTF-8: <error> Cause: Decryption succeeded, but the resulting bytes could not be interpreted as valid UTF-8 text. This most commonly means the file was encrypted with a non-UTF-8 encoding, or the decrypted data has been corrupted. Fix: Ensure your original .env file is saved with UTF-8 encoding before encrypting. Re-create the .env.enc from a UTF-8 encoded source file.

​
Native binary fails to load

encryptd includes a Rust-compiled native addon (.node file). If you are running on a platform or libc variant for which no prebuilt binary exists, Node.js will fail to load the addon and throw an error at import time. Fix: Check that your environment matches one of the supported platforms:
Alpine Linux (musl libc) and Linux ARM64 are not currently supported. If you run encryptd inside a Docker container, make sure the base image uses a glibc-based Linux distribution such as Debian or Ubuntu not node:alpine.
If you need Alpine support, consider using node:lts-slim (Debian-slim) as your Docker base image instead of node:lts-alpine.

​
Package installation fails from GitHub Packages

Cause: encryptd is published to GitHub Packages, not the public npm registry. Without the correct .npmrc configuration, npm install will attempt to resolve @vernonthedev/encryptd from the public registry and fail with a 404 or authentication error. Fix: Create or update .npmrc in your project root (or in your home directory for a global install) to redirect the @vernonthedev scope to GitHub Packages:
.npmrc
Then install the package:
Terminal
If the package is in a private repository, you will also need to authenticate with a GitHub Personal Access Token (PAT) that has read:packages scope. Add //npm.pkg.github.com/:_authToken=YOUR_PAT to your .npmrc or set it as the NODE_AUTH_TOKEN environment variable.