Troubleshooting

Diagnostics and fixes for every major class of xenvsync error — from decrypt failures and key permissions to team access, CI injection, and export issues.

First-Response Diagnostics

Run these commands firstbash

# Check version and environment
$ xenvsync version

# Show sync state of all xenvsync files
$ xenvsync status

# Full security audit (permissions, gitignore, key strength, vault integrity)
$ xenvsync doctor

# Structural + cryptographic vault validation
$ xenvsync verify

Important: Always run diagnostics from the repository root that contains your target vault and key files. Running from a subdirectory is a common source of "file not found" errors.

Decryption Failures

authentication failed — vault decryption error

Cause: The key used to decrypt does not match the key that encrypted the vault. This happens when the wrong .xenvsync.key is present, the vault came from a different project, or the vault was tampered with.

Fixbash

# Run the full diagnostic
$ xenvsync doctor
$ xenvsync verify

# Check which key file is present
$ ls -la .xenvsync.key

# Compare key fingerprint against team roster if using V2
$ xenvsync whoami

# If key is wrong, obtain the correct key from the vault owner
# then re-run:
$ xenvsync pull

vault file not found / no such file .env.vault

Cause: The vault has not been created yet, or you are running xenvsync from the wrong directory.

Fixbash

# Verify you are in the repo root
$ ls .env.vault

# If missing, create the vault by encrypting your .env
$ xenvsync push

# For named environments, specify --env
$ xenvsync push --env staging

no key file found — .xenvsync.key missing

Cause: The symmetric key file is absent. It was never initialized, was gitignored and not restored, or was deleted.

Fixbash

# Initialize a new key (only if starting fresh — this invalidates the old vault)
$ xenvsync init

# If vault already exists, obtain the key from the person who created it
# Place it at:
$ ls .xenvsync.key
# Set correct permissions
$ chmod 600 .xenvsync.key

passphrase required — enc: prefix detected

Cause: The key file was created with --passphrase and requires XENVSYNC_PASSPHRASE to be set before xenvsync can use it.

Fixbash

# Export the passphrase before running any xenvsync command
$ export XENVSYNC_PASSPHRASE="your-passphrase"
$ xenvsync pull

# In CI, inject via secrets manager:
# GitHub Actions example
# env:
#   XENVSYNC_PASSPHRASE: ${{ secrets.XENVSYNC_PASSPHRASE }}

Key & Permission Errors

key file readable by others — permission warning

Cause: xenvsync expects .xenvsync.key and ~/.xenvsync/identity to be owner-only (mode 0600). Broader permissions are a security risk.

Fixbash

# Fix key file permissions (Linux / macOS)
$ chmod 600 .xenvsync.key

# Fix identity file permissions
$ chmod 600 ~/.xenvsync/identity

# Confirm with doctor
$ xenvsync doctor

key not in .gitignore — doctor warning

Cause: The .xenvsync.key file is not listed in .gitignore. Committing it would expose the decryption key.

Fixbash

# Add to .gitignore manually
$ echo ".xenvsync.key" >> .gitignore
$ echo ".env" >> .gitignore
$ git add .gitignore

# Or re-run init which auto-updates .gitignore
$ xenvsync init --force

key strength warning — all-zeros or weak key

Cause: doctor detected a key that is all zeros or appears too weak to provide security.

Fixbash

# Generate a fresh strong key
$ xenvsync init --force

# Then re-encrypt the vault with the new key
$ xenvsync push

Stale Vault & Sync Issues

.env is newer than .env.vault — stale vault warning

Cause: The plaintext .env was edited after the last push. The vault does not reflect current secrets.

Fixbash

# Preview what changed
$ xenvsync diff

# Re-encrypt with current .env contents
$ xenvsync push

# Verify the updated vault
$ xenvsync verify

diff shows unexpected changes

Cause: A diff that shows changes you did not make may indicate that another team member pushed changes, or that the vault was rotated.

Fixbash

# Show full diff (key names only by default — no values)
$ xenvsync diff

# To see values explicitly (use with care)
$ xenvsync diff --show-values

# Check vault Git history for recent changes
$ xenvsync log

Team & V2 Vault Access

no identity file found — team member cannot decrypt

Cause: The member has not generated their X25519 identity, or the identity file was deleted.

Fixbash

# Generate identity (run on the member's machine)
$ xenvsync keygen

# Print public key to share with vault maintainer
$ xenvsync whoami

recipient not in roster — V2 decryption failed

Cause: The member's public key was not included in the roster when the vault was last encrypted. Either they were never added, or rotation was performed without them.

Fixbash

# Maintainer: add the member and rotate
$ xenvsync team add alice <alice-public-key>
$ xenvsync rotate
$ xenvsync push

# Member: pull after maintainer rotates
$ xenvsync pull

member removed but can still decrypt old vault

Cause: Removing from roster does not retroactively re-encrypt. Rotation is required to exclude the revoked identity.

Fixbash

# Revoke access and rotate in one step
$ xenvsync rotate --revoke former-member

# Confirm roster
$ xenvsync team list

.xenvsync-team.json not committed

Cause: The team roster file is needed by all members. It must be committed to the repository.

Fixbash

$ git add .xenvsync-team.json
$ git commit -m "Add team roster"

CI/CD Injection Failures

xenvsync pull fails in CI — key not available

Cause: The key was not injected into the CI environment. CI jobs do not have the .xenvsync.key file by default.

Fixbash

# Inject key from CI secret into file
# GitHub Actions example:
# - run: echo "${{ secrets.XENVSYNC_KEY }}" > .xenvsync.key && chmod 600 .xenvsync.key

# For passphrase-protected keys, also set:
# env:
#   XENVSYNC_PASSPHRASE: ${{ secrets.XENVSYNC_PASSPHRASE }}

# Then pull or run as normal
$ xenvsync pull
$ xenvsync run -- npm run build

run command exits with unexpected code

Cause: xenvsync run preserves child exit codes. A non-zero exit comes from the child process, not xenvsync itself.

Fixbash

# Debug by running the child process directly after pulling
$ xenvsync pull
$ npm run build  # run child independently to see its error

# Alternatively, inspect the child environment
$ xenvsync run -- env | grep YOUR_VAR

Export Errors

export --format=shell produces invalid output

Cause: Values are single-quote escaped to prevent shell expansion. If a value itself contains a single quote, the escaping handles it. This is the secure behavior.

Fixbash

# Verify export output looks correct
$ xenvsync export --format=shell

# Supported formats: dotenv, json, yaml, shell, tfvars
$ xenvsync export --format=json
$ xenvsync export --format=yaml

YAML export has unquoted boolean-like values

Cause: YAML 1.1 treats yes/no/on/off as booleans. xenvsync v1.12.0+ quotes these automatically.

Fixbash

# Upgrade to v1.12.0 or later
$ xenvsync version

# Re-export after upgrading
$ xenvsync export --format=yaml

Multi-Environment Issues

wrong environment loaded — unexpected variables

Cause: Fallback merging layers .env.shared → .env.<name> → .env.local. A variable from .env.shared may be overriding your expectation.

Fixbash

# Disable fallback to use only the named env file
$ xenvsync push --no-fallback --env production
$ xenvsync pull --no-fallback --env production

# Discover all environments in the project
$ xenvsync envs

# Check status of a specific env
$ xenvsync status --env staging

invalid environment name — path traversal error

Cause: Environment names must not contain slashes or .. characters. This is a security check.

Fixbash

# Valid environment names
$ xenvsync push --env staging
$ xenvsync push --env prod
$ xenvsync push --env feature-auth

# Invalid (will error)
# xenvsync push --env ../etc
# xenvsync push --env prod/v2

Still Stuck?

If none of the above resolves your issue, collect diagnostic output and open a GitHub issue:

Collect diagnosticsbash

$ xenvsync version
$ xenvsync doctor
$ xenvsync verify
$ xenvsync status

File a bug at github.com/nasimstg/xenvsync/issues with the output from the commands above and your OS / Go version.

PreviousUse Cases Next Commands