Troubleshooting

Troubleshooting

sops: command not found or SOPS binary error

Every operation that touches secret files calls the sops binary. If it is not on your PATH, those operations will fail.

Fix: Install SOPS and verify it works:

sops --version

If SOPS is installed to a non-standard location, point Keyseal to it in keyseal.yaml:

sops:
  binary: /usr/local/bin/sops

---

keyseal.yaml not found in <cwd>; run keyseal init first

Every command except init looks for keyseal.yaml in the current working directory. You are either in the wrong directory or the file does not exist.

Fix:

# confirm you are in the right directory
ls keyseal.yaml

# if it does not exist, initialize
keyseal init

---

Placeholder recipients in .sops.yaml

After keyseal init, the generated .sops.yaml contains:

age: age1REPLACE_ME,age1RECOVERY_REPLACE_ME

SOPS will not encrypt with these values. Doctor will flag them as failures.

Fix: Replace with real age public keys:

# if you need to generate a key pair
age-keygen -o ~/.config/sops/age/keys.txt
# note the public key from the output, then edit .sops.yaml

---

sops encrypt fails with "no matching creation rules"

SOPS cannot find a creation rule in .sops.yaml that matches the target file path.

Common cause: The path_regex in your creation rule does not match the path you are trying to encrypt. The regex is matched against the final destination path, or the --filename-override value passed by keyseal add.

Example: if your target is production/platform/app.enc.yaml but your rule is:

path_regex: production/platform/.*\.enc\.yaml$

and you have repository.root: ., the path passed to SOPS is relative to where you ran keyseal add. Verify the regex with:

# test the regex against your path
echo "production/platform/app.enc.yaml" | grep -E "production/platform/.*\.enc\.yaml$"

---

Plaintext file at an .enc.yaml path

Doctor will report:

[fail] production/platform/app.enc.yaml: appears to be plaintext rather than SOPS-encrypted content

This means the file at that path is valid YAML that matches the secret document schema but has no SOPS metadata. It was never actually encrypted.

How this happens: The file was written manually or copied from an example without going through keyseal add or sops encrypt.

Fix:

# remove the plaintext file
rm production/platform/app.enc.yaml

# recreate it properly
keyseal add production/platform/app

# then edit to set real values
keyseal edit production/platform/app

Do not commit a plaintext .enc.yaml file to the repository.

---

render refuses to write because mode is unsafe

Error: mode 0644 is not owner-only; use --force to override

The file mode you specified (or the default in keyseal.yaml) would give read access to group or world users.

Fix: Use 0600 (the default):

keyseal render production/platform/app --out /run/secrets/app.env --mode 0600

Or if you genuinely need a less restrictive mode for your deployment:

keyseal render production/platform/app --out ./app.env --mode 0644 --force

---

render or exec fails with schema validation error

Keyseal validates the decrypted secret document after every decrypt. Common causes:

• A key in values does not match validation.key_pattern (default requires uppercase + digits + underscores only). This is usually a key with a lowercase letter or a hyphen.
• The values map is empty and validation.require_values is true.
• The document has version: 0 or is missing version.

Fix: Run keyseal edit <logical-name> to fix the document, or adjust validation.key_pattern in keyseal.yaml if lowercase keys are intentional.

---

keyseal add fails with "unknown template"

Error: unknown template "my-template"

Only four templates exist: laravel, stripe, mail, mysql-app. Template names are case-sensitive.

Fix: Check the available templates in Templates or omit --template to use the default single-key starter.

---

keyseal add fails with "file already exists"

The target .enc.yaml file already exists and you did not pass --force.

Fix:

# overwrite the existing file
keyseal add production/platform/app --force

# or just edit the existing file
keyseal edit production/platform/app

---

keyseal doctor exits 1 with no visible error

Doctor exits 1 when any check has status fail. The failure is printed to stdout, not stderr. If you are running in a context that suppresses stdout, redirect it:

keyseal doctor 2>&1
# or use JSON to separate structured output
keyseal doctor --json

---

Logical name validation errors

Error: invalid logical name "production/platform/app.enc.yaml": name must not end with .yaml

Common logical name mistakes:

Bad input	Problem
production/platform/app.enc.yaml	Do not include the file extension
/production/platform/app	Logical names must be relative
production/../platform/app	No path traversal
production//platform/app	No empty segments

---

Build produces version dev

If you build without make build (e.g. go build ./cmd/keyseal), the ldflags that inject version metadata are not set. The binary will report keyseal dev.

Fix: Always use make build or make dist for any build you care about the version string of.

---

Release archive extraction issues

Each release archive contains the binary, README.md, and LICENSE in a top-level directory named after the archive. Extract with:

tar xzf keyseal_v0.1.0_linux_amd64.tar.gz
# produces: keyseal_v0.1.0_linux_amd64/keyseal

Verify the checksum before using the binary:

sha256sum -c keyseal_v0.1.0_checksums.txt --ignore-missing

---

SOPS decryption fails with "no key was able to decrypt"

Your age private key is not at the location SOPS expects, or the file was encrypted with a different key.

SOPS reads the age private key from SOPS_AGE_KEY_FILE. The default is ~/.config/sops/age/keys.txt. Check:

# check the env var
echo $SOPS_AGE_KEY_FILE

# verify the key file exists
ls ~/.config/sops/age/keys.txt

# try decrypting directly with sops to isolate the issue
sops --decrypt production/platform/app.enc.yaml

Doctor will report the SOPS error output (up to 3 lines) when decryption fails.