Troubleshooting - Dotfiles Manager

This page covers common issues you may encounter when setting up or using the dotfiles, along with their solutions.

Bootstrap Issues

Error: Script Exits Immediately

Symptom:

bash -c "$(curl -fsLS https://raw.githubusercontent.com/yurgenlira/dotfiles/main/bootstrap.sh)"
# Script exits without explanation

Cause: Running the script as root or with sudo. Solution:

# DO NOT run with sudo
bash -c "$(curl -fsLS https://raw.githubusercontent.com/yurgenlira/dotfiles/main/bootstrap.sh)"

# The script will request sudo when needed

Why: The script uses set -e (exit on error) and explicitly checks for root:

if [ "$(id -u)" -eq 0 ]; then
    echo "Error: Please do not run this script as root/sudo."
    exit 1
fi

apt-get Command Not Found

Symptom:

bash: apt-get: command not found

Cause: Not running on a Debian/Ubuntu-based system. Solution: This dotfiles setup is designed for Ubuntu/Debian. For other distributions:

Manually install required tools:
- ansible
- age
- bw (Bitwarden CLI)
- chezmoi
- git
- curl
Then proceed with:
```
chezmoi init --apply yurgenlira
```

Snap Installation Fails

Symptom:

error: cannot communicate with server: Post "http://localhost/v2/snaps/bw": dial unix /run/snapd.socket: connect: no such file or directory

Cause: snapd service is not running or not installed. Solution:

# Check if snapd is running
sudo systemctl status snapd

# Start snapd if stopped
sudo systemctl start snapd
sudo systemctl enable snapd

# If not installed, bootstrap.sh will install it
sudo apt-get install -y snapd

Alternative: The script automatically falls back to npm installation for Bitwarden CLI and curl installation for chezmoi if snap is unavailable.

Bitwarden Issues

Symptom:

bw login
Email address: [email protected]
Master password: ****
Error: Username or password is incorrect. Try again.

Possible causes and solutions:

1. Incorrect Credentials

Verify credentials by logging into the web vault at https://vault.bitwarden.com

2. Self-Hosted Instance

If using a self-hosted Bitwarden server:

bw config server https://your-bitwarden-server.com
bw login

3. Two-Factor Authentication

If 2FA is enabled:

bw login --method <method> --code <code>

# Methods:
# 0 = Authenticator app
# 1 = Email
# 3 = YubiKey

# Example with authenticator:
bw login --method 0 --code 123456

4. API Rate Limiting

Wait a few minutes and try again if you see:

Error: Rate limit exceeded. Try again later.

Bitwarden Session Expired

Symptom:

chezmoi apply
Error: Not logged in.

Cause: BW_SESSION environment variable is not set or expired. Solution:

# Check vault status
bw status

# If locked:
export BW_SESSION=$(bw unlock --raw)

# Or use the helper function:
source ~/.bash_functions
bw_unlock

Persistent solution: Add to ~/.bashrc:

# Auto-check Bitwarden status on shell startup
if command -v bw &> /dev/null; then
    if bw status | grep -q '"status":"locked"'; then
        echo "Bitwarden vault is locked. Run 'bw_unlock' to unlock."
    fi
fi

Cannot Find Secret in Bitwarden

Symptom:

chezmoi apply
Error: template: dot_ssh/private_id_rsa.tmpl:1: function "bitwarden" not available

Cause: Secret note doesn’t exist in Bitwarden or has wrong name. Solution:

List all items:
```
bw list items | jq -r '.[].name'
```
Check specific note:
```
bw get item "ssh-private-key"
```
Create missing note:
- Log into Bitwarden web vault
- Create Secure Note with exact name (case-sensitive)
- Paste secret content
- Save
- Sync CLI: bw sync

Expected secret names:

chezmoi-age-key - Age encryption key
SSH keys as configured in templates

Age Encryption Issues

Age Key Not Found

Symptom:

chezmoi apply
Error: age: failed to decrypt: no identity matched any of the recipients

Cause: Missing or incorrect age key at ~/.config/chezmoi/key.txt. Solution:

Check if key exists:
```
ls -la ~/.config/chezmoi/key.txt
```

If missing, retrieve from Bitwarden:

bw get notes "chezmoi-age-key" > ~/.config/chezmoi/key.txt
chmod 600 ~/.config/chezmoi/key.txt

If not in Bitwarden, you need the original key or must re-encrypt all files:

# Generate new key
age-keygen -o ~/.config/chezmoi/key.txt

# Re-encrypt all files in the repository
# (This requires access to the unencrypted versions)

Prevention: Always save the age key to Bitwarden immediately after generation.

Wrong Age Key Permissions

Symptom:

WARNING: Permissions 0644 for '/home/user/.config/chezmoi/key.txt' are too open.

Cause: Age key file has overly permissive file permissions. Solution:

chmod 600 ~/.config/chezmoi/key.txt
chown $(id -u):$(id -g) ~/.config/chezmoi/key.txt

Verify:

ls -la ~/.config/chezmoi/key.txt
# Should show: -rw------- 1 user user 184 Jan 15 10:30 key.txt

Cannot Decrypt File

Symptom:

chezmoi apply
Error: failed to decrypt ~/.ssh/id_rsa: no identity matched

Cause: File was encrypted with a different age key. Solution:

Verify current key’s public key:

age-keygen -y ~/.config/chezmoi/key.txt

Check which key was used to encrypt:

head -1 ~/.local/share/chezmoi/private_dot_ssh/private_id_rsa.age
# Shows: age-encryption.org/v1
# Second line shows recipient public key

If keys don’t match, you need the correct key from:
- Another machine where it works
- Your backup/password manager
- Re-encrypt the file with current key (if you have unencrypted version)

Chezmoi Issues

chezmoi init Fails

Symptom:

chezmoi init --apply yurgenlira
Error: cannot find GitHub repository

Cause: Network issue or repository doesn’t exist. Solution:

Check network connectivity:
```
ping github.com
```

Verify repository exists:

curl -I https://github.com/yurgenlira/dotfiles

Try with full URL:

chezmoi init --apply https://github.com/yurgenlira/dotfiles.git

Use SSH instead of HTTPS:

chezmoi init --apply [email protected]:yurgenlira/dotfiles.git

Template Execution Error

Symptom:

chezmoi apply
Error: template: dot_bashrc.tmpl:15: undefined variable "email"

Cause: Missing template variable in chezmoi config. Solution:

Check current config:
```
chezmoi data
```
Re-run init to answer prompts:
```
chezmoi init
```

Or manually edit config:

chezmoi edit-config

Add missing variables:

[data]
    email = "[email protected]"

Files Not Applied

Symptom: Files exist in repository but are not in home directory after chezmoi apply. Cause: Conditional templates excluding files based on OS or machine type. Solution:

Check what would be applied:
```
chezmoi diff
```
See which files are managed:
```
chezmoi managed
```

Verify template conditions:

chezmoi cat ~/.bash_aliases
# Shows processed template output

Check your config data:
```
chezmoi data | grep machine_type
```

Example: WSL aliases only load when:

{{- if and (eq .chezmoi.os "linux") (contains "microsoft" .chezmoi.kernel.osrelease) }}

Ansible Issues

Ansible Playbook Fails

Symptom:

Running Ansible playbooks...
ERROR! couldn't resolve module/action 'community.general.dconf'

Cause: Missing Ansible collections. Solution:

cd ~/.local/share/chezmoi/ansible
ansible-galaxy collection install -r requirements.yml

Package Installation Fails

Symptom:

fatal: [local]: FAILED! => {"msg": "No package matching 'antigravity' is available"}

Cause: Repository not added or GPG key issue. Solution:

Check if repository is configured:
```
ls /etc/apt/sources.list.d/
```
Verify GPG key:
```
ls -la /etc/apt/keyrings/
```

Manually run repository setup:

cd ~/.local/share/chezmoi/ansible
ansible-playbook site.yml --tags common --ask-become-pass

Check for errors in apt:

sudo apt update
# Look for GPG errors or repository failures

Permission Denied During Ansible Run

Symptom:

fatal: [local]: FAILED! => {"msg": "Missing sudo password"}

Cause: Ansible needs sudo privileges but password wasn’t provided. Solution:

cd ~/.local/share/chezmoi/ansible
ansible-playbook site.yml --ask-become-pass
# Enter your sudo password when prompted

Git Configuration Issues

Wrong Git Identity

Symptom: Commits show wrong name/email in work repositories. Cause: Conditional git config not matching repository path. Solution:

Check current config:
```
cd ~/work/repo
git config user.email
```
Check conditionalInclude paths:
```
cat ~/.gitconfig
```
Verify work gitconfig:
```
cat ~/.gitconfig-work
```

Fix path matching:

chezmoi edit ~/.gitconfig

Ensure paths match your actual directory structure:

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

SSH Issues

SSH Key Not Loaded

Symptom:

git clone [email protected]:user/repo.git
Permission denied (publickey).

Cause: SSH key not added to ssh-agent or wrong permissions. Solution:

Check key permissions:

ls -la ~/.ssh/
# Private keys should be 600
# Public keys should be 644

Fix permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub

Add key to agent:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

Verify key is loaded:
```
ssh-add -l
```
Test connection:
```
ssh -T [email protected]
```

AWS Configuration Issues

AWS Profile Not Found

Symptom:

aws_env production
profile 'production' not found

Cause: Profile doesn’t exist in ~/.aws/credentials. Solution:

List existing profiles:
```
aws configure list-profiles
```
Check credentials file:
```
cat ~/.aws/credentials
```

If empty, re-apply dotfiles:

# Ensure Bitwarden is unlocked
bw_unlock

# Re-apply to pull AWS credentials
chezmoi apply --force

Verify credentials were populated:

cat ~/.aws/credentials | grep -A 3 "[production]"

Environment Variables Not Set

Symptom:

aws s3 ls
Unable to locate credentials

Cause: AWS environment variables not exported. Solution:

Use aws_env function:

source ~/.bash_functions
aws_env production

Verify variables are set:
```
env | grep AWS
```

Expected output:

AWS_PROFILE=production
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1

General Debugging

Enable Verbose Output

For chezmoi:

chezmoi apply -v
# Even more verbose:
chezmoi apply -vv

For Ansible:

ansible-playbook site.yml -vv --ask-become-pass

For bash scripts:

bash -x bootstrap.sh

Check Logs

# System logs
sudo journalctl -xe

# Chezmoi state
chezmoi doctor

# Ansible facts
ansible local -m setup

Clean State and Retry

# Remove chezmoi state
rm -rf ~/.local/share/chezmoi

# Re-initialize
chezmoi init --apply yurgenlira

Warning: This will delete local modifications to dotfiles.

Getting Help

If you encounter issues not covered here:

Check chezmoi documentation: https://www.chezmoi.io/
Check Bitwarden CLI docs: https://bitwarden.com/help/cli/
Check age documentation: https://github.com/FiloSottile/age
Review repository issues: https://github.com/yurgenlira/dotfiles/issues

Reporting Issues

When reporting issues, include:

Output of chezmoi doctor
Operating system and version: lsb_release -a
Error messages (full output)
Steps to reproduce
What you expected to happen

Example:

# Gather diagnostic info
echo "=== System Info ==="
lsb_release -a

echo "=== Chezmoi Doctor ==="
chezmoi doctor

echo "=== Tool Versions ==="
ansible --version
bw --version
age --version

Get Started

Core Concepts

Configuration

Ansible Automation

Secrets Management

Platform Support

Development

Reference

​Bootstrap Issues

​Error: Script Exits Immediately

​apt-get Command Not Found

​Snap Installation Fails

​Bitwarden Issues

​Bitwarden Login Fails

​1. Incorrect Credentials

​2. Self-Hosted Instance

​3. Two-Factor Authentication

​4. API Rate Limiting

​Bitwarden Session Expired

​Cannot Find Secret in Bitwarden

​Age Encryption Issues

​Age Key Not Found

​Wrong Age Key Permissions

​Cannot Decrypt File

​Chezmoi Issues

​chezmoi init Fails

​Template Execution Error

​Files Not Applied

​Ansible Issues

​Ansible Playbook Fails

​Package Installation Fails

​Permission Denied During Ansible Run

​Git Configuration Issues

​Wrong Git Identity

​SSH Issues

​SSH Key Not Loaded

​AWS Configuration Issues

​AWS Profile Not Found

​Environment Variables Not Set

​General Debugging

​Enable Verbose Output

​Check Logs

​Clean State and Retry

​Getting Help

​Reporting Issues

Build docs developers (and LLMs) love

Bootstrap Issues

Error: Script Exits Immediately

apt-get Command Not Found

Snap Installation Fails

Bitwarden Issues

Bitwarden Login Fails

1. Incorrect Credentials

2. Self-Hosted Instance

3. Two-Factor Authentication

4. API Rate Limiting

Bitwarden Session Expired

Cannot Find Secret in Bitwarden

Age Encryption Issues

Age Key Not Found

Wrong Age Key Permissions

Cannot Decrypt File

Chezmoi Issues

chezmoi init Fails

Template Execution Error

Files Not Applied

Ansible Issues

Ansible Playbook Fails

Package Installation Fails

Permission Denied During Ansible Run

Git Configuration Issues

Wrong Git Identity

SSH Issues

SSH Key Not Loaded

AWS Configuration Issues

AWS Profile Not Found

Environment Variables Not Set

General Debugging

Enable Verbose Output

Check Logs

Clean State and Retry

Getting Help

Reporting Issues