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.

Installation & Setup Issues
Configuration Problems
Channel Connectivity
Message Handling
Runtime & Performance
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:

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.

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

推荐订阅源

DEV Community