TuyaOpen Troubleshooting Handbook: Solve 20 Common Issues

TuyaOpen Troubleshooting Handbook: Solve 20 Common Issues

Quick Reference Guide | Updated 2026 | For TuyaOpen v2.x+

---

Introduction

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.

---

Table of Contents

1. Installation & Setup Issues
2. Configuration Problems
3. Channel Connectivity
4. Message Handling
5. Runtime & Performance
6. Advanced Troubleshooting

---

1. Installation & Setup Issues

Issue #1: 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

---

Issue #2: Missing Dependencies After Clone

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
git clone
cd
npm install
tuyaopen start

shell

---

Issue #3: Node.js Version Mismatch

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"
  }
}

---

2. Configuration Problems

Issue #4: Environment Variables Not Loading

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}`);
  }
});

---

Issue #5: Invalid JSON in config.json

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!"

---

Issue #6: Channel Configuration Not Applied

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`);
}

---

3. Channel Connectivity

Issue #7: Discord Bot Not Responding

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:
  1. Go to https://discord.com/developers/applications
  2. Select your bot
  3. Navigate to "Bot" → "Privileged Gateway Intents"
  4. Enable "Message Content Intent"
• Test with a simple ping command first

---

Issue #8: Telegram Webhook Errors

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 });
}

---

Issue #9: WebSocket Connection Drops

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.maxRetries) {
        this.retries++;
        console.log(`Reconnecting (${this.retries}/${this.maxRetries})...`);
        setTimeout(() => 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

---

Issue #10: Rate Limiting Errors

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.windowMs);

    if (this.tokens.length >= 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

---

4. Message Handling

Issue #11: Messages Not Being Processed

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);
    }
  };
}

---

Issue #12: Message Encoding Issues (Emoji/Special Characters)

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

---

Issue #13: Context Loss Between Messages

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));
}

---

Issue #14: Command Parsing Failures

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

---

5. Runtime & Performance

Issue #15: Memory Leaks

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

---

Issue #16: Slow Response Times

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 < this.ttlMs) {
      return cached.data;
    }

    const data = await computeFn();
    this.cache.set(key, { data, timestamp: Date.now() });
    return data;
  }

  clear() {
    this.cache.clear();
  }
}

// Usage
const cache = new ResponseCache();
const response = await cache.get(message.hash, () => 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

---

Issue #17: Unhandled Promise Rejections

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

---

Issue #18: Database Connection Pool Exhaustion

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');
}

---

6. Advanced Troubleshooting

Issue #19: Debugging Production Issues

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

---

Issue #20: Security Vulnerabilities

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

---

Quick Reference Card

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

---

Conclusion

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:

1. Always validate configuration before deployment
2. Implement comprehensive logging from day one
3. Use monitoring and alerting for production systems
4. Keep dependencies updated and audit regularly
5. 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.

---

Resources

• 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