Common issues and solutions for InteractKit projects
Dependencies not found after scaffolding
The CLI automatically runs npm install, but if it fails or you need to reinstall:
cd my-interactkit-bot-appnpm install
Module not found errors
Ensure you're running from the project root directory and dependencies are installed:
npm installnpm run build
Environment variables not loading
Ensure .env file exists in project root
Check that dotenv is configured in src/index.ts
Restart the development server after changes
cp .env.example .env# Edit .env with your API keysnpm run dev
Missing API keys error
Check that all required environment variables are set for your selected providers. Refer to the Environment Variables guide for required keys.
TypeScript compilation errors
Verify Node.js version 18 or higher
Check import paths are correct
Ensure tsconfig.json has experimentalDecorators enabled
node --version # Should be v18 or highernpm run build # Check for specific errors
Decorator errors
InteractKit uses TypeScript decorators. Ensure your tsconfig.json includes:
tsconfig.json
{"compilerOptions": {"experimentalDecorators": true,"emitDecoratorMetadata": true}}
Session events not firing
Check Session.ts handlers are properly defined
Verify SDK connectivity and API key
Check transport configuration (e.g., Twilio)
Bot not responding
Verify LLM provider API key is valid
Check console logs for error messages
Ensure initialize() method returns valid provider instances
CLI command not found
Prefer global installation and run commands directly:
interactkit create-appinteractkit add-bot MyBot
add-toolkit fails
Ensure bot exists in src/bots/[BotName]/
Run command from project root directory
Check bot name spelling matches exactly
Deployment build fails
Test build locally first: npm run build
Check platform logs for specific errors
Verify Node.js version matches local (18+)
Process exits immediately after deployment
Verify all environment variables are set on platform
Check that sdk.keepRunning() is called
Review platform logs for errors