clan-core/docs/site/guides/vars/vars-troubleshooting.md

Troubleshooting Vars

Quick reference for diagnosing and fixing vars issues.

Common Issues

Generator Script Fails

Symptom: Error during clan vars generate or deployment

Possible causes and solutions:

1. Missing runtime inputs

   # Wrong - missing required tool
   runtimeInputs = [ ];
   script = ''
     openssl rand -hex 32 > $out/secret  # openssl not found!
   '';
   
   # Correct
   runtimeInputs = [ pkgs.openssl ];
   

2. Wrong output path

   # Wrong - must use $out
   script = ''
     echo "secret" > ./myfile
   '';
   
   # Correct
   script = ''
     echo "secret" > $out/myfile
   '';
   

3. Missing declared files

   files."config" = { };
   files."key" = { };
   script = ''
     # Wrong - only generates one file
     echo "data" > $out/config
   '';
   
   # Correct - must generate all declared files
   script = ''
     echo "data" > $out/config
     echo "key" > $out/key
   '';
   

Cannot Access Generated Files

Symptom: "attribute 'value' missing" or file not found

Solutions:

1. Secret files don't have .value

   # Wrong - secret files can't use .value
   files."secret" = { secret = true; };
   # ...
   environment.etc."app.conf".text = 
     config.clan.core.vars.generators.app.files."secret".value;
   
   # Correct - use .path for secrets
   environment.etc."app.conf".source = 
     config.clan.core.vars.generators.app.files."secret".path;
   

2. Public files should use .value

   # Better for non-secrets
   files."cert.pem" = { secret = false; };
   # ...
   sslCertificate = 
     config.clan.core.vars.generators.ca.files."cert.pem".value;
   

Dependencies Not Available

Symptom: "No such file or directory" when accessing $in/...

Solution: Declare dependencies correctly

clan.core.vars.generators.child = {
  # Wrong - missing dependency
  script = ''
    cat $in/parent/file > $out/newfile
  '';
  
  # Correct
  dependencies = [ "parent" ];
  script = ''
    cat $in/parent/file > $out/newfile
  '';
};

Permission Denied

Symptom: Service cannot read generated secret file

Solution: Set correct ownership and permissions

files."service.key" = {
  secret = true;
  owner = "myservice";  # Match service user
  group = "myservice";
  mode = "0400";       # Read-only for owner
};

Vars Not Regenerating

Symptom: Changes to generator script don't trigger regeneration

Solution: Use --regenerate flag

clan vars generate my-machine --generator my-generator --regenerate

Prompts Not Working

Symptom: Script fails with "No such file or directory" for prompts

Solution: Access prompts correctly

# Wrong
script = ''
  echo $password > $out/file
'';

# Correct
prompts.password.type = "hidden";
script = ''
  cat $prompts/password > $out/file
'';

Debugging Techniques

1. Check Generator Status

See what vars are set:

clan vars list my-machine

2. Inspect Generated Files

For shared vars:

ls -la vars/shared/my-generator/

For per-machine vars:

ls -la vars/per-machine/my-machine/my-generator/

3. Test Generators Locally

Create a test script to debug:

# test-generator.nix
{ pkgs ? import <nixpkgs> {} }:
pkgs.stdenv.mkDerivation {
  name = "test-generator";
  buildInputs = [ pkgs.openssl ];  # Your runtime inputs
  buildCommand = ''
    # Your generator script here
    mkdir -p $out
    openssl rand -hex 32 > $out/secret
    ls -la $out/
  '';
}

Run with:

nix-build test-generator.nix

4. Enable Debug Logging

Set debug mode:

clan --debug vars generate my-machine

5. Check File Permissions

Verify generated secret permissions:

# On the target machine
ls -la /run/secrets/

Recovery Procedures

Regenerate All Vars

If vars are corrupted or need refresh:

# Regenerate all for a machine
clan vars generate my-machine --regenerate

# Regenerate specific generator
clan vars generate my-machine --generator my-generator --regenerate

Manual Secret Injection

For recovery or testing:

# Set a var manually (bypass generator)
echo "temporary-secret" | clan vars set my-machine my-generator/my-file

Restore from Backup

Vars are stored in the repository:

# Restore previous version
git checkout HEAD~1 -- vars/

# Check and regenerate if needed
clan vars list my-machine

Storage Backend Issues

SOPS Decryption Fails

Symptom: "Failed to decrypt" or permission errors

Solution: Ensure your user/machine has the correct age keys configured. Clan manages encryption keys automatically based on the configured users and machines in your flake.

Check that:

1. Your machine is properly configured in the flake

2. Your user has access to the machine's secrets

3. The age key is available in the expected location

Password Store Issues

Symptom: "pass: store not initialized"

Solution: Initialize password store:

export PASSWORD_STORE_DIR=/path/to/clan/vars
pass init your-gpg-key

Getting Help

If these solutions don't resolve your issue:

1. Check the clan-core issue tracker

2. Ask in the Clan community channels

3. Provide:

   • The generator configuration

   • The exact error message

   • Output of clan --debug vars generate