TuyaOpen Troubleshooting Handbook: Solve 20 Common Issues Quick Reference Guide | Updated 2026 | For TuyaOpen v2.x+ TuyaOpen has become one of the most popular frameworks for building AI agents with multi-channel communication capabilities. However, like any powerful tool, it comes with its own set of challenges. After working with TuyaOpen in production environments and helping dozens of developers debug their implementations, I've compiled this comprehensive troubleshooting handbook. This guide covers 20 common issues you'll encounter when working with TuyaOpen, complete with solutions, code examples, and prevention strategies. Whether you're dealing with configuration problems, channel connectivity issues, or runtime errors, you'll find actionable solutions here. Let's dive in. Installation & Setup Issues Configuration Problems Channel Connectivity Message Handling Runtime & Performance Advanced Troubleshooting tuyaopen Command Not Found Problem: $ tuyaopen --version bash: tuyaopen: command not found Root Cause: The TuyaOpen CLI isn't installed globally or isn't in your PATH. Solution: # Install globally via npm npm install -g tuyaopen # Or install locally and use npx npm install tuyaopen npx tuyaopen --version # Verify installation which tuyaopen # Should return: /usr/local/bin/tuyaopen Prevention: Always use npm install -g for CLI tools you'll use frequently Add ~/.npm-global/bin to your PATH if using local installations Verify installation immediately after setup Problem: $ tuyaopen start Error: Cannot find module '@tuyaopen/core' Root Cause: Dependencies weren't installed after cloning the repository. Solution: # Navigate to project directory cd your-tuyaopen-project # Install all dependencies npm install # Or use yarn/pnpm yarn install # or pnpm install # Verify node_modules exists ls -la node_modules | head -20 Prevention: Always run npm install after cloning Add a post-clone script to your README: ## Quick Start bash shell Problem: $ tuyaopen init my-agent Error: TuyaOpen requires Node.js v18.0.0 or higher. Current version: v16.14.0 Root Cause: Outdated Node.js version. Solution: # Check current version node --version # Update using nvm (recommended) nvm install 20 nvm use 20 nvm alias default 20 # Or download from nodejs.org # https://nodejs.org/en/download/ # Verify update node --version # Should show v18+ npm --version Prevention: Add .nvmrc file to your project: # .nvmrc 20 Use engines field in package.json: { "engines": { "node": ">=18.0.0" } } Problem: $ tuyaopen start Error: TUYAOPEN_API_KEY is not defined Root Cause: .env file missing or not properly formatted. Solution: # Check if .env file exists ls -la .env # Verify .env content cat .env # Should contain: TUYAOPEN_API_KEY=your_api_key_here TUYAOPEN_API_SECRET=your_secret_here TUYAOPEN_CHANNEL_DISCORD=your_discord_token # Load environment variables source .env # Or use dotenv in your code require('dotenv').config(); Prevention: Create .env.example with placeholder values: # .env.example TUYAOPEN_API_KEY=your_api_key_here TUYAOPEN_API_SECRET=your_secret_here TUYAOPEN_CHANNEL_DISCORD=your_discord_token Add .env to .gitignore Validate env vars on startup: // config/validate.js const required = ['TUYAOPEN_API_KEY', 'TUYAOPEN_API_SECRET']; required.forEach(key => { if (!process.env[key]) { throw new Error(`Missing required env var: ${key}`); } }); Problem: $ tuyaopen start SyntaxError: Unexpected token } in JSON at position 245 Root Cause: Malformed JSON configuration file. Solution: # Validate JSON syntax cat config.json | jq . # Or use node to parse node -e "console.log(JSON.parse(require('fs').readFileSync('config.json')))" # Common fixes: # - Remove trailing commas # - Ensure all strings use double quotes # - Close all brackets properly Example of corrected config.json: { "agent": { "name": "MyAgent", "version": "1.0.0" }, "channels": { "discord": { "enabled": true, "token": "${DISCORD_TOKEN}" }, "telegram": { "enabled": false } } } Prevention: Use a JSON linter in your editor (VS Code: JSON Tools extension) Validate JSON before committing: # Add to pre-commit hook jq . config.json > /dev/null || echo "Invalid JSON!" Problem: $ tuyaopen start Info: Starting agent... Warning: No channels enabled. Agent will not receive messages. Root Cause: All channels disabled in configuration. Solution: // Check config/channels.js const channels = { discord: { enabled: true, // Must be true token: process.env.DISCORD_TOKEN, intents: ['GUILDS', 'GUILD_MESSAGES'] }, telegram: { enabled: true, token: process.env.TELEGRAM_BOT_TOKEN } }; // Verify in code console.log('Enabled channels:', Object.entries(channels) .filter(([_, config]) => config.enabled) .map(([name]) => name) ); Prevention: Add startup validation: // src/validate-config.js function validateChannels(config) { const enabled = Object.values(config.channels) .filter(ch => ch.enabled).length; if (enabled === 0) { throw new Error('At least one channel must be enabled'); } console.log(`✓ ${enabled} channel(s) enabled`); } Problem: Info: Discord connection established Warning: No messages received after 5 minutes Root Cause: Missing intents or incorrect event handlers. Solution: // config/discord.js module.exports = { token: process.env.DISCORD_TOKEN, intents: [ 'GUILDS', 'GUILD_MESSAGES', 'MESSAGE_CONTENT' // Critical for reading messages ], partials: ['CHANNEL'] }; // src/handlers/discord.js client.on('messageCreate', async (message) => { if (message.author.bot) return; console.log(`Received: ${message.content}`); // Your handling logic here }); Prevention: Enable Message Content Intent in Discord Developer Portal: Go to https://discord.com/developers/applications Select your bot Navigate to "Bot" → "Privileged Gateway Intents" Enable "Message Content Intent" Test with a simple ping command first Problem: Error: ETELEGRAM: 409 Conflict: terminated by other getUpdates request Root Cause: Using both polling and webhook simultaneously. Solution: // Choose ONE method: // Option A: Polling (development) const bot = new Telegraf(process.env.TELEGRAM_TOKEN); bot.launch({ dropPendingUpdates: true }); // Option B: Webhook (production) const bot = new Telegraf(process.env.TELEGRAM_TOKEN); await bot.telegram.setWebhook('https://your-domain.com/webhook'); bot.launch({ webhook: { domain: 'your-domain.com' } }); // Never mix both methods Prevention: Use environment variable to switch modes: const mode = process.env.TELEGRAM_MODE || 'polling'; if (mode === 'webhook') { await bot.telegram.setWebhook(process.env.WEBHOOK_URL); bot.launch({ webhook: { domain: process.env.WEBHOOK_DOMAIN } }); } else { bot.launch({ dropPendingUpdates: true }); } Problem: Warning: WebSocket disconnected. Reconnecting... Error: Connection timeout after 30s Root Cause: Network instability or missing reconnection logic. Solution: // src/connection-manager.js class ConnectionManager { constructor(config) { this.maxRetries = 5; this.retryDelay = 5000; this.retries = 0; } async connect() { try { await this.establishConnection(); this.retries = 0; } catch (error) { if (this.retries this.connect(), this.retryDelay); } else { throw new Error('Max retries exceeded'); } } } async establishConnection() { // Your connection logic return new Promise((resolve, reject) => { const ws = new WebSocket(this.url); ws.on('open', resolve); ws.on('error', reject); ws.on('close', () => this.connect()); }); } } Prevention: Implement exponential backoff: const delay = Math.min(1000 * Math.pow(2, retries), 30000); Use heartbeat/ping-pong mechanism Monitor connection health with periodic checks Problem: Error: 429 Too Many Requests Retry-After: 60 Root Cause: Exceeding API rate limits. Solution: // src/rate-limiter.js class RateLimiter { constructor(limit, windowMs) { this.limit = limit; this.windowMs = windowMs; this.tokens = []; } async throttle() { const now = Date.now(); // Remove old tokens this.tokens = this.tokens.filter(t => now - t = this.limit) { const oldestToken = this.tokens[0]; const waitTime = this.windowMs - (now - oldestToken); console.log(`Rate limited. Waiting ${waitTime}ms...`); await this.sleep(waitTime); } this.tokens.push(now); } sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } } // Usage const limiter = new RateLimiter(10, 60000); // 10 requests per minute async function sendMessage() { await limiter.throttle(); // Send message } Prevention: Check API documentation for rate limits Implement request queuing Cache responses when possible Use batch operations instead of individual requests Problem: Info: Message received from user123 [No further output - message not processed] Root Cause: Event handler not properly registered or async/await missing. Solution: // ❌ Wrong: Missing async/await client.on('message', (message) => { processMessage(message); // Fire and forget }); // ✅ Correct: Proper async handling client.on('message', async (message) => { try { await processMessage(message); } catch (error) { console.error('Message processing failed:', error); await message.reply('Sorry, something went wrong.'); } }); // Ensure handler is registered before connection function setupHandlers(client) { client.on('message', handleMessage); console.log('✓ Message handlers registered'); } Prevention: Add handler registration logging Use try-catch in all async handlers Implement error boundaries: function withErrorHandler(handler) { return async (...args) => { try { return await handler(...args); } catch (error) { logError(error); notifyAdmin(error); } }; } Problem: Received: "Hello 😀" // Broken emoji Expected: "Hello 😀" Root Cause: Incorrect character encoding. Solution: // Ensure UTF-8 encoding everywhere process.env.NODE_ENV = 'production'; process.env.LANG = 'en_US.UTF-8'; // In your code const message = Buffer.from(rawMessage, 'utf-8').toString('utf-8'); // For file operations fs.writeFileSync('output.txt', content, { encoding: 'utf-8' }); // Database connection const connection = await mysql.createConnection({ charset: 'utf8mb4', // Full UTF-8 support // ... }); Prevention: Set encoding in all file operations Use utf8mb4 for MySQL/MariaDB Validate encoding in CI/CD pipeline: # Check file encoding file -i your-file.js # Should show: charset=utf-8 Problem: User: "What's the weather?" Bot: "Which city?" User: "Beijing" Bot: "I don't understand the context." // Should remember previous conversation Root Cause: Conversation state not being maintained. Solution: // src/context-manager.js class ContextManager { constructor() { this.contexts = new Map(); } getContext(userId) { if (!this.contexts.has(userId)) { this.contexts.set(userId, { conversation: [], metadata: {}, createdAt: Date.now() }); } return this.contexts.get(userId); } addMessage(userId, role, content) { const context = this.getContext(userId); context.conversation.push({ role, content, timestamp: Date.now() }); // Keep last 20 messages if (context.conversation.length > 20) { context.conversation = context.conversation.slice(-20); } } clearContext(userId) { this.contexts.delete(userId); } } // Usage const contextManager = new ContextManager(); async function handleUserMessage(userId, message) { contextManager.addMessage(userId, 'user', message); const context = contextManager.getContext(userId); const response = await generateResponse(context.conversation); contextManager.addMessage(userId, 'assistant', response); return response; } Prevention: Implement context persistence (Redis/database) Set context expiration policies Add context debugging commands: if (message === '/debug context') { const context = contextManager.getContext(userId); reply(JSON.stringify(context, null, 2)); } Problem: User: "/start bot" Bot: [No response] Expected: Bot should start Root Cause: Command parser not handling variations. Solution: // src/command-parser.js class CommandParser { constructor(prefix = '/') { this.prefix = prefix; this.commands = new Map(); } register(name, handler, options = {}) { this.commands.set(name.toLowerCase(), { handler, aliases: options.aliases || [], description: options.description || '' }); } parse(content) { const trimmed = content.trim(); if (!trimmed.startsWith(this.prefix)) return null; const parts = trimmed.slice(1).split(/\s+/); const command = parts[0].toLowerCase(); const args = parts.slice(1); // Check direct match if (this.commands.has(command)) { return { command, args, handler: this.commands.get(command).handler }; } // Check aliases for (const [name, config] of this.commands) { if (config.aliases.includes(command)) { return { command: name, args, handler: config.handler }; } } return null; } } // Usage const parser = new CommandParser(); parser.register('start', async (args, message) => { await message.reply('Bot started!'); }, { aliases: ['begin', 'init'], description: 'Start the bot' }); parser.register('help', async (args, message) => { const help = Array.from(parser.commands.entries()) .map(([name, config]) => `/${name} - ${config.description}`) .join('\n'); await message.reply(help); }); Prevention: Document all commands in README Add command validation tests Implement command autocomplete for supported platforms Problem: Warning: Memory usage exceeds 512MB Process killed by OOM killer Root Cause: Unbounded data structures or event listener accumulation. Solution: // src/memory-monitor.js class MemoryMonitor { constructor(threshold = 512 * 1024 * 1024) { this.threshold = threshold; this.checkInterval = null; } start() { this.checkInterval = setInterval(() => { const usage = process.memoryUsage(); const heapUsed = usage.heapUsed; console.log(`Memory: ${(heapUsed / 1024 / 1024).toFixed(2)}MB`); if (heapUsed > this.threshold) { console.warn('⚠️ High memory usage detected!'); this.triggerGC(); } }, 60000); } triggerGC() { if (global.gc) { global.gc(); console.log('✓ Manual GC triggered'); } else { console.warn('Run with --expose-gc to enable manual GC'); } } stop() { clearInterval(this.checkInterval); } } // Prevent event listener leaks class SafeEventEmitter { constructor(maxListeners = 10) { this.emitter = new EventEmitter(); this.emitter.setMaxListeners(maxListeners); } on(event, listener) { const count = this.emitter.listenerCount(event); if (count >= this.emitter.getMaxListeners()) { console.warn(`Too many listeners for ${event}`); } this.emitter.on(event, listener); } removeListener(event, listener) { this.emitter.removeListener(event, listener); } } Prevention: Run with --expose-gc flag Use WeakMap/WeakSet for caches Implement TTL for all caches Profile memory regularly: node --inspect app.js # Then use Chrome DevTools Memory tab Problem: User sends message [15 seconds later] Bot responds Root Cause: Blocking operations or inefficient algorithms. Solution: // src/performance-optimizer.js // Use async operations async function processMessage(message) { // ❌ Blocking // const data = fs.readFileSync('data.json'); // ✅ Non-blocking const data = await fs.promises.readFile('data.json', 'utf-8'); // Use worker threads for CPU-intensive tasks if (isCPUIntensive(message)) { return await runInWorker(message); } return processNormally(message); } // Implement caching class ResponseCache { constructor(ttlMs = 60000) { this.cache = new Map(); this.ttlMs = ttlMs; } async get(key, computeFn) { const cached = this.cache.get(key); if (cached && Date.now() - cached.timestamp generateResponse(message)); Prevention: Add response time monitoring: const start = Date.now(); await processMessage(message); console.log(`Response time: ${Date.now() - start}ms`); Set performance budgets Use database indexes Implement lazy loading Problem: (node:1234) UnhandledPromiseRejectionWarning: Error: Network timeout Root Cause: Missing catch blocks or error handlers. Solution: // Global error handler process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled Rejection at:', promise); console.error('Reason:', reason); // Log to error tracking service logError(reason); // Don't exit in production if (process.env.NODE_ENV !== 'production') { process.exit(1); } }); // Wrap all async operations async function safeExecute(fn, fallback = null) { try { return await fn(); } catch (error) { console.error('Operation failed:', error.message); return fallback; } } // Usage const result = await safeExecute( () => fetchUserData(userId), { id: userId, name: 'Unknown' } ); Prevention: Enable strict mode in package.json: { "scripts": { "start": "node --unhandled-rejections=strict src/index.js" } } Use ESLint rule no-floating-promises Always wrap top-level await in try-catch Problem: Error: Connection pool exhausted. Max connections: 10 Root Cause: Connections not being released or pool size too small. Solution: // src/database.js const { Pool } = require('pg'); const pool = new Pool({ max: 20, // Max connections idleTimeoutMillis: 30000, // Close idle connections after 30s connectionTimeoutMillis: 2000, }); // Always release connections async function query(text, params) { const client = await pool.connect(); try { const result = await client.query(text, params); return result; } finally { client.release(); // Critical! } } // Monitor pool status setInterval(() => { console.log('Pool stats:', { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount }); }, 60000); Prevention: Use connection pooling libraries Implement query timeouts Monitor pool metrics Add circuit breakers: if (pool.waitingCount > 10) { throw new Error('Database overloaded'); } Problem: Error occurs in production No logs available Cannot reproduce locally Root Cause: Insufficient logging and monitoring. Solution: // src/logger.js const winston = require('winston'); const logger = winston.createLogger({ level: process.env.LOG_LEVEL || 'info', format: winston.format.combine( winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json() ), defaultMeta: { service: 'tuyaopen-agent' }, transports: [ new winston.transports.File({ filename: 'logs/error.log', level: 'error' }), new winston.transports.File({ filename: 'logs/combined.log' }) ] }); // Add correlation IDs const { v4: uuidv4 } = require('uuid'); function withCorrelationId(fn) { return async (...args) => { const correlationId = uuidv4(); logger.info({ correlationId, event: 'request_start' }); try { return await fn(...args); } finally { logger.info({ correlationId, event: 'request_end' }); } }; } // Usage app.post('/message', withCorrelationId(async (req, res) => { logger.info({ message: req.body }); // Process message })); Prevention: Implement structured logging Add distributed tracing Set up alerting for error rates Create runbooks for common issues Problem: Security audit reveals: - Outdated dependencies with CVEs - Hardcoded secrets in code - Missing input validation Root Cause: Security not integrated into development workflow. Solution: // src/security.js // Input validation const { z } = require('zod'); const MessageSchema = z.object({ userId: z.string().uuid(), content: z.string().max(1000), timestamp: z.number() }); function validateMessage(data) { try { return MessageSchema.parse(data); } catch (error) { throw new Error(`Invalid message: ${error.message}`); } } // Secret management function getSecret(name) { const value = process.env[name]; if (!value) { throw new Error(`Missing secret: ${name}`); } return value; } // Rate limiting for security const limiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15 minutes max: 100, // limit each IP to 100 requests per windowMs message: 'Too many requests, please try again later' }); Prevention: Run security audits regularly: npm audit npm audit fix Use secrets management (AWS Secrets Manager, HashiCorp Vault) Implement input validation on all user inputs Keep dependencies updated: npm install -g npm-check-updates ncu -u npm install Add security scanning to CI/CD: # .github/workflows/security.yml security-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: npm audit --audit-level=high - run: npm run lint Issue Category Common Symptoms First Thing to Check Installation Command not found which tuyaopen Configuration Env var errors cat .env Connectivity Connection drops Network/firewall Messages No responses Event handlers Performance Slow responses Memory/CPU usage Security Audit failures npm audit Troubleshooting TuyaOpen applications requires a systematic approach. Start with the basics (installation, configuration), then move to connectivity, message handling, and finally performance optimization. Key Takeaways: Always validate configuration before deployment Implement comprehensive logging from day one Use monitoring and alerting for production systems Keep dependencies updated and audit regularly Test error scenarios in development Remember: The best troubleshooting is prevention. Invest time in proper setup, monitoring, and testing, and you'll spend far less time debugging in production. Official Documentation: https://tuyaopen.ai/docs GitHub Repository: https://github.com/tuyaopen/tuyaopen Community Discord: https://discord.gg/tuyaopen Issue Tracker: https://github.com/tuyaopen/tuyaopen/issues Found this helpful? Share it with your team and contribute your own troubleshooting tips to the TuyaOpen community! Last updated: April 2026 | TuyaOpen v2.x