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
namecheap-dns config init

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

Check:

• ✅ File exists at ~/.namecheap-dns.yaml or ./configs/.namecheap-dns.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
namecheap-dns account list

# Verify account name spelling
# Create the account if it doesn't exist
namecheap-dns 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	namecheap-dns account show	Update credentials in Namecheap
❌ IP not whitelisted	curl ifconfig.me	Add IP to Namecheap whitelist
❌ Sandbox in production	namecheap-dns account show | grep sandbox	Set use_sandbox: false
❌ Network issues	ping api.namecheap.com	Check internet connection

Solutions:

# 1. Verify your account configuration
namecheap-dns account show

# 2. Check if using sandbox mode
namecheap-dns account show | grep sandbox

# 3. Verify your IP address
curl ifconfig.me

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

"Invalid API key"

Problem: The API key is incorrect or expired.

Solution:

1. Log in to Namecheap
2. Go to Profile → Tools → API Access
3. Verify your API key
4. Update it in your config:

   namecheap-dns account edit <account-name>

"IP address not whitelisted"

Problem: Your current IP address is not in the whitelist.

Solution:

1. Get your current IP:

   curl ifconfig.me

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

   namecheap-dns account edit <account-name>

DNS Record Issues

"Record already exists"

Problem: Trying to add a record that already exists.

Solution:

# List existing records
namecheap-dns dns list <domain>

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

# Or delete first, then add
namecheap-dns dns delete <domain> <host> <type>
namecheap-dns 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
namecheap-dns 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
namecheap-dns 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
namecheap-dns domain list

# Verify domain name spelling
# Check if using correct account
namecheap-dns --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:

  namecheap-dns domain check <domain>

Permission Issues

"Permission denied" on config file

Problem: Config file has wrong permissions.

Solution:

# Fix permissions
chmod 600 ~/.namecheap-dns.yaml
chmod 600 ./configs/.namecheap-dns.yaml

Build/Installation Issues

"Command not found"

Problem: Binary not in PATH.

Solution:

# Add to PATH
export PATH=$PATH:/path/to/namecheap-dns

# Or install to system
make install

# Or use full path
/path/to/namecheap-dns --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:

namecheap-dns domain list -v

Report Issues

If you encounter a bug or need help:

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

Community Support

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

Debug Mode

For advanced debugging, you can:

1. Check configuration:

   namecheap-dns config show

2. Validate configuration:

   namecheap-dns config validate

3. Test API connection:

   namecheap-dns account show
   namecheap-dns domain list