Troubleshooting

Troubleshooting

Configuration Issues

No config file found

# Create config file
zonekit config init

# Verify location
ls -la ~/.zonekit.yaml
ls -la ./configs/.zonekit.yaml

# Check permissions
chmod 600 ~/.zonekit.yaml

Account not found

# List available accounts
zonekit account list

# Add missing account
zonekit account add <account-name>

API Connection Issues

Common Causes and Solutions

Issue	Check	Solution
Invalid credentials	zonekit account show	Update API key and username
IP not whitelisted	curl ifconfig.me	Whitelist IP in provider settings
Sandbox mode	grep use_sandbox ~/.zonekit.yaml	Set use_sandbox: false
Wrong provider	zonekit account show	Verify provider field
Network issues	ping api.namecheap.com	Check internet connection

Invalid API key

1. Log in to your provider account
2. Navigate to API settings
3. Verify/regenerate API key
4. Update configuration:

zonekit account edit <account-name>

IP address not whitelisted

# Get current IP
curl ifconfig.me

# Add to provider whitelist (Namecheap: Profile → Tools → API Access)

# Update config if needed
zonekit account edit <account-name>

DNS Record Issues

Record already exists

# List existing records
zonekit dns list <domain>

# Update instead of add
zonekit dns update <domain> <host> <type> <value>

# Or delete then add
zonekit dns delete <domain> <host> <type>
zonekit dns add <domain> <host> <type> <value>

Record not found

# Verify record exists
zonekit dns list <domain> | grep <host>

# Remember: Use @ for root domain
zonekit dns add example.com @ A 192.0.2.1

Invalid record type

Supported types: A, AAAA, CNAME, MX, TXT, NS, SRV

# Check type is valid
zonekit dns add example.com www A 192.0.2.1

Domain Issues

Domain not found

# List all domains
zonekit domain list

# Check with specific account
zonekit --account <name> domain list

Domain not available

# Check availability
zonekit domain check <domain>

Installation Issues

Command not found

# Add to PATH
export PATH=$PATH:/path/to/zonekit

# Or install system-wide
make install

# Or use full path
/path/to/zonekit --version

Build errors

# Check Go version (1.22+ required)
go version

# Update dependencies
go mod download
go mod tidy

# Clean rebuild
make clean
make build

Getting Help

Debug Commands

# Show configuration
zonekit config show

# Validate configuration
zonekit config validate

# Test API connection
zonekit account show
zonekit domain list

Report Issues

When reporting bugs, include:

• Error message
• Steps to reproduce
• Configuration (mask API keys)
• Version: zonekit --version

Submit issues: github.com/SamyRai/zonekit/issues