Troubleshooting Guide#
This guide provides solutions for common issues you might encounter when deploying, configuring, or using the CopperX Payout Bot.Webhook Issues#
Problem: Telegram Bot Not Responding to Commands#
Bot doesn't respond to any commands
No error messages in logs
1.
Verify your SERVER_URL in .env points to a public HTTPS URL
Check that the URL is properly formed with no trailing slash
Run npm run setup to update the webhook with Telegram
2.
Ensure your server is publicly accessible
Verify that port 443 (or your configured port) is open
Check if your server uses a self-signed certificate (not accepted by Telegram)
3.
Firewall or Network IssuesCheck server firewall settings
If using a cloud provider, verify security group rules
Ensure outbound connections to Telegram API are allowed
4.
Verify that the bot process is running
Authentication Issues#
Problem: Login OTP Never Arrives#
User attempts to log in but never receives OTP email
Bot times out waiting for OTP
1.
Email Configuration at CopperXVerify that the email service at CopperX is functioning correctly
Check if the email might be in the user's spam folder
Confirm that the user's email is registered with CopperX
2.
Ensure your COPPERX_API_KEY in .env is valid and correct
Check for any API usage limits or restrictions
3.
Network Connectivity to CopperX APIVerify network connectivity to the CopperX API
Check for any firewalls blocking outbound connections to the API
Problem: Authentication Succeeds But Features Don't Work#
User can log in but cannot use wallet or transfer features
Error messages about authentication required
1.
Check Redis connection and verify tokens are being stored
Look for Redis connection errors in logs
Verify Redis database URL in .env
2.
Check if tokens are expired
Look for token refresh mechanisms in the code
Verify the expireAt timestamp stored in the session
3.
User may have successfully authenticated but lacks KYC verification
Check logs for KYC status check failures
Verify KYC status with CopperX API
Redis Issues#
Problem: Redis Connection Failures#
Error messages about Redis connection
Session data not persisting
Rate limiting not functioning
1.
Incorrect Connection StringVerify REDIS_DATABASE_URL in .env
Test the connection string manually
2.
If using local Redis, ensure it's running
If using Upstash or another provider, check service status
3.
Check for firewalls blocking Redis connections
Verify network access to Redis host
4.
Ensure Redis password is correct in connection string
Verify Redis ACL settings if applicable
Wallet and Transfer Issues#
Problem: Wallet Balance Not Showing#
Wallet command executes but shows no balance
Error messages about API failures
1.
API Response Format ChangedCheck logs for API response parsing errors
Verify API response format against code expectations
2.
User may not have a default wallet set
Check logs for errors related to default wallet
Guide the user to set a default wallet
3.
Authentication Token IssuesToken may be expired or invalid
Check logs for authentication errors during API calls
Problem: Transfers Fail#
Transfer command executes but transfers don't complete
Error messages about transfer failures
1.
Verify user has sufficient balance for the transfer
Check for fees that might not be accounted for
2.
Verify recipient email or wallet address is valid
Check logs for errors related to recipient lookup
3.
Look for specific API error messages in logs
Check for rate limiting or throttling by CopperX API
Rate Limiting Issues#
Problem: Too Many Rate Limit Errors#
Users frequently see rate limit error messages
Bot operations are being throttled
1.
Rate Limit Too RestrictiveAdjust rate limit parameters in src/utils/rate-limit/rate-limit.service.ts
2.
Redis Issues Affecting Rate Limit TrackingVerify Redis connection for rate limit storage
Check for Redis errors in logs during rate limit checks
3.
Consider scaling the bot deployment if legitimate traffic is high
Analyze usage patterns to optimize rate limits
Logging and Debugging#
Unclear why certain errors are occurring
Difficulty tracing user journeys
1.
Modify logger configuration to include more detail
Add additional log points in problematic code areas
2.
Ensure logs include context like chatId, userId, etc.
3.
Set up log aggregation tools like Papertrail, Loggly, or ELK stack
Configure log rotation to prevent log files from growing too large
Deployment Issues (Railway)#
Problem: Railway Deployment Fails#
Deployment to Railway fails
Application doesn't start after deployment
1.
Check Railway build logs for compilation errors
Verify that all dependencies are properly declared in package.json
2.
Ensure all required environment variables are set in Railway
Check for typos in environment variable names
3.
Verify that the port used by the application matches Railway's expectations
Railway typically uses PORT env var, ensure your app respects it:
4.
Check if application is running out of memory
Consider optimizing memory usage or upgrading service plan
5.
Verify the startup command in railway.json is correct
"startCommand": "npm run start"
General Troubleshooting Approach#
1.
Always start by checking logs in /logs directory
Look for specific error messages and timestamps
2.
Double-check .env file for correct API keys, URLs, and tokens
Ensure all required environment variables are set
3.
Use tools like Postman or curl to test API endpoints directly
Verify that the CopperX API is accessible from your server
4.
Sometimes simply restarting the bot resolves issues
If using PM2: pm2 restart <process-id>
If using systemd: systemctl restart copperx-bot.service
5.
Keep dependencies up-to-date to avoid compatibility issues
Run npm audit fix to address security vulnerabilities
6.
Monitor CPU, memory, and disk usage
Ensure system has adequate resources for the bot
7.
Add a health check endpoint to your Express app
Monitor the bot's health regularly
Modified at 2025-03-23 17:03:35
