Troubleshooting

Using envctl doctor

The doctor command checks your envctl setup and identifies problems:

$ envctl doctor
✓ envctl version 1.0.0
✓ Identity configured (alice-macbook)
✓ Daemon running (PID 12345)
✓ P2P port 7834 accessible
! Relay not configured
✓ Project 'myapp' found

All checks passed (1 warning)

Auto-Fix

Use --fix to automatically resolve some issues:

$ envctl doctor --fix
✓ Identity configured
✗ Stale socket file found
  ✓ Removed stale socket
✓ Daemon started

Common Error Messages

"No identity found"

Cause: You haven't initialized your identity yet.

Solution:

$ envctl init

"Invalid passphrase"

Cause: The passphrase you entered doesn't match the one used to encrypt your identity.

Solutions:

• Try your passphrase again carefully
• Check if caps lock is on
• If you've forgotten it, recover from your paper backup:

  $ envctl identity recover

"Not in an envctl project"

Cause: The current directory doesn't have a .envctl/ folder.

Solutions:

• Navigate to a directory with an envctl project
• Create a new project: envctl project create
• Link an existing project: envctl join <invite-code>
• Use the --project flag to specify a project

"Daemon not running"

Cause: The background daemon isn't started.

Solution:

$ envctl daemon start

"Port 7834 already in use"

Cause: Another process is using the P2P port, or a previous daemon instance didn't shut down cleanly.

Solutions:

1. Check for existing daemon:

   $ envctl daemon status

2. Stop the daemon:

   $ envctl daemon stop

3. If that doesn't work, find and kill the process:

   $ lsof -i :7834
   $ kill <PID>

4. Use a different port:

   $ envctl daemon start --p2p-port 7835

"No YubiKey found"

Cause: Your YubiKey isn't connected or the smart card service isn't running.

Solutions:

• Ensure the YubiKey is properly inserted
• On Linux, start the smart card daemon:

  $ sudo systemctl start pcscd

• Try removing and reinserting the YubiKey

"Invalid invite code"

Cause: The invitation code is malformed, expired, or already used.

Solutions:

• Ask the inviter to generate a new invitation
• Ensure you copied the entire code
• Invites expire after 10 minutes by default—request a longer TTL:

  $ envctl project invite bob --pubkey ... --ttl 30m

"Invalid key name" (when setting variables)

Cause: Variable names must be uppercase letters, numbers, and underscores only.

Valid names: API_KEY, DATABASE_URL, AWS_SECRET_ACCESS_KEY

Invalid names: api-key, database.url, my secret

Sync Issues

Changes Not Syncing to Peers

1. Check daemon status:

   $ envctl daemon status
   ✓ Daemon running
     Connected peers: 2

2. Check if peers are connected:

   $ envctl status
   ✓ Synced with 2 peers

3. Force a push:

   $ envctl push

4. Check relay status (if using relay):

   $ envctl project relay status

Not Receiving Updates from Peers

1. Pull manually:

   $ envctl pull

2. Restart the daemon:

   $ envctl daemon stop
   $ envctl daemon start

3. Verify you have access to the environment:

   $ envctl env list

Peers Not Discovering Each Other

On the same local network, peers should discover each other via mDNS. If not:

1. Check that both machines have the daemon running
2. Ensure mDNS isn't blocked by firewall
3. Add peers manually:

   $ envctl peers add 192.168.1.100:7834

4. Use the relay for remote teams:

   $ envctl project relay set relay.envctl.dev

Daemon Problems

Daemon Won't Start

1. Check for stale socket:

   $ rm ~/.config/envctl/envctl.sock
   $ envctl daemon start

2. Check logs:

   $ envctl log --since 5m --level error

3. Run in foreground for debugging:

   $ envctl daemon run

Daemon Crashes

1. Check system resources (memory, disk space)
2. Check logs:

   $ envctl log --level error

3. Update envctl:

   $ curl -fsSL https://raw.githubusercontent.com/uradical/envctl/main/install.sh | sh

4. Report the issue with logs on GitHub

Daemon Using Too Much Memory

The daemon caches some data for performance. If memory usage is excessive:

1. Restart the daemon:

   $ envctl daemon stop && envctl daemon start

2. Report the issue with details about your project size

CI/CD Issues

"No CI keypair found"

Solution: Generate a CI keypair (requires the daemon to be running):

$ envctl ci keygen

The public key is automatically stored on the team chain and synced to all project members.

"Invalid CI key" in Pipeline

Causes and solutions:

• Secret not set: Add ENVCTL_CI_KEY to your CI platform's secrets
• Whitespace in key: Ensure no extra newlines when copying the key
• Wrong key: The private key must match the public key on the team chain
• Key rotated: If you regenerated the keypair, update the CI secret

"Bundle decryption failed"

Cause: The bundle was encrypted with a different CI key.

Solution: Re-export the bundle with the current key:

$ envctl ci export -e prod -o .envctl/prod.enc
$ git add .envctl/prod.enc && git commit -m "Re-export secrets" && git push

Environment Issues

.env File Not Written

1. Check permissions on the directory
2. Verify you have access to the environment:

   $ envctl env list

3. Check if secrets exist:

   $ envctl env var list

Wrong Secrets Loaded

• Check current environment:

  $ envctl status

• Check for local overrides: Look for .env.<environment> files
• Use --no-overrides:

  $ envctl env use dev --no-overrides

Getting Help

Gather Diagnostic Information

# Version info
$ envctl version --full

# Health check
$ envctl doctor

# Recent logs
$ envctl log --since 1h --level error

# Daemon status
$ envctl daemon status

Reporting Issues

When reporting an issue on GitHub, include:

• envctl version (envctl version --full)
• Operating system and version
• Output of envctl doctor
• Steps to reproduce the issue
• Error messages (sanitize any sensitive information)