Troubleshooting

Troubleshooting

Solve common issues and get help

---

Common Issues and Solutions

Configuration Issues

"No config file found"

Problem: The tool cannot find your configuration file.

Solution:

# Create a new config file
zonekit config init

# Or manually create it
mkdir -p ~/.zonekit.yaml
# Edit the file with your credentials

Check:

• File exists at ~/.zonekit.yaml or ./configs/.zonekit.yaml
• File has correct permissions (chmod 600)
• File is readable

"Account not found"

Problem: The specified account doesn't exist.

Solution:

# List all available accounts
zonekit account list

# Verify account name spelling
# Create the account if it doesn't exist
zonekit account add <account-name>

Check:

• Account name is spelled correctly
• Account exists in config file
• Use account list to see all accounts

API Connection Issues

"API connection failed"

Possible causes:

Cause	How to Check	Solution
Incorrect API credentials	zonekit account show	Update credentials in provider settings
IP not whitelisted	curl ifconfig.me	Add IP to provider whitelist (Namecheap)
Sandbox in production	zonekit account show | grep sandbox	Set use_sandbox: false
Wrong provider	zonekit account show	Verify provider field matches intended provider
Network issues	ping api.namecheap.com	Check internet connection

Solutions:

# 1. Verify your account configuration
zonekit account show

# 2. Check if using sandbox mode
zonekit account show | grep sandbox

# 3. Verify your IP address
curl ifconfig.me

# 4. Update IP in provider API settings if changed
# For Namecheap: Profile → Tools → API Access → Whitelist IP

"Invalid API key"

Problem: The API key is incorrect or expired.

Solution:

1. Log in to your DNS provider account (e.g., Namecheap)
2. Go to API settings (for Namecheap: Profile → Tools → API Access)
3. Verify your API key
4. Update it in your config:

   zonekit account edit <account-name>

"IP address not whitelisted"

Problem: Your current IP address is not in the whitelist (applies to Namecheap provider).

Solution:

1. Get your current IP:

   curl ifconfig.me

2. Add it to provider API whitelist:
   • For Namecheap: Go to Profile → Tools → API Access
   • Add your IP address
3. Update config if IP changed:

   zonekit account edit <account-name>

DNS Record Issues

"Record already exists"

Problem: Trying to add a record that already exists.

Solution:

# List existing records
zonekit dns list <domain>

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

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

"Record not found"

Problem: Trying to update/delete a record that doesn't exist.

Solution:

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

# Check exact hostname and type
# Use '@' for root domain, not empty string

"Invalid record type"

Problem: Using an unsupported record type.

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

# Use correct type
zonekit dns add example.com www A 192.0.2.1

Domain Issues

"Domain not found"

Problem: The domain doesn't exist in your account.

Solution:

# List all your domains
zonekit domain list

# Verify domain name spelling
# Check if using correct account
zonekit --account <account-name> domain list

"Domain not available"

Problem: Domain is not available for registration.

Solution:

• Domain may already be registered
• Domain may be in redemption period
• Check domain status:

  zonekit domain check <domain>

Permission Issues

"Permission denied" on config file

Problem: Config file has wrong permissions.

Solution:

# Fix permissions
chmod 600 ~/.zonekit.yaml
chmod 600 ./configs/.zonekit.yaml

Build/Installation Issues

"Command not found"

Problem: Binary not in PATH.

Solution:

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

# Or install to system
make install

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

Build errors

Problem: Errors when building from source.

Solution:

# Ensure Go 1.22+ is installed
go version

# Update dependencies
go mod download
go mod tidy

# Clean and rebuild
make clean
make build

Getting More Help

Check Logs

The tool may output error messages to stderr. Check the output for detailed error information.

Enable Verbose Mode

Some commands support verbose output:

zonekit domain list -v

Report Issues

If you encounter a bug or need help:

1. Check existing issues: https://github.com/SamyRai/zonekit/issues
2. Create a new issue with:
   • Error message
   • Steps to reproduce
   • Your configuration (mask API keys)
   • Version: zonekit --version

Community Support

• GitHub Issues: https://github.com/SamyRai/zonekit/issues
• GitHub Discussions: (if enabled)

Debug Mode

For advanced debugging, you can:

1. Check configuration:

   zonekit config show

2. Validate configuration:

   zonekit config validate

3. Test API connection:

   zonekit account show
   zonekit domain list