Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://dev.docs.inworld.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Installation Issues

​

”Permission denied” during installation

npm install -g @inworld/cli
# Error: EACCES: permission denied

sudo npm install -g @inworld/cli

# Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Then install without sudo
npm install -g @inworld/cli

​

“inworld: command not found” after installation

npm list -g @inworld/cli
# Should show the installed package

# Find where npm installs global packages
npm config get prefix

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

​

Node.js version issues

node --version
# Must be v18 or higher

# Install nvm if not already installed
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 20+
nvm install 20
nvm use 20
nvm alias default 20

​

Authentication Issues

​

Login opens browser but fails

inworld login --force

# Clear cached credentials and retry
inworld logout
inworld login

# Check status
inworld status

​

”Authentication Error” on commands

inworld status

# Token expired? Re-authenticate
inworld login --force

# Wrong workspace? Select correct one
inworld workspace select

# Verify API key is set (for deployed apps)
echo $INWORLD_API_KEY

​

Multiple workspaces confusion

inworld workspace select
# Shows interactive list of available workspaces

inworld status
# Shows currently active workspace

​

Local Development Issues

​

”Graph compilation failed”

# Compile TypeScript directly to check for syntax errors
npx tsc --noEmit ./graph.ts

// ❌ Wrong
const graph = new GraphBuilder({
  apiKey: process.env.INWORLD_API_KEY
})

// ✅ Correct  
const graph = new GraphBuilder({
  id: 'my-graph-id',  // Required!
  apiKey: process.env.INWORLD_API_KEY
})

npm install  # Make sure all packages are installed

​

“Module not found” errors

# In your project directory
npm install

# Verify package.json exists
ls -la package.json

// ✅ Correct import
import { GraphBuilder, LLMChatNode } from '@inworld/runtime';

// ❌ Wrong import path
import { GraphBuilder } from 'inworld-runtime';

​

inworld serve not starting

# Default port 3000 in use?
lsof -i :3000

# Use different port
inworld serve ./graph.ts --port 8080

# Test graph compilation first
inworld run ./graph.ts '{"input":"test"}'

# If that works, then try serve
inworld serve ./graph.ts

​

inworld run hangs or times out

# Verify API key is set
echo $INWORLD_API_KEY

# Or set it for the session
export INWORLD_API_KEY="your-key-here"

# Try minimal input first
inworld run ./graph.ts '{"input":"hi"}'

# Then gradually add complexity
inworld run ./graph.ts '{
  "input": {"message": "hello"},
  "userContext": {"targetingKey": "test"}
}'

​

Project Issues

​

inworld init creates empty project

# Initialize with the llm-to-tts-node template
inworld init --template llm-to-tts-node --name my-project

# If template fails, create manually
mkdir my-project && cd my-project
npm init -y
npm install @inworld/runtime

# Copy example from docs or templates

​

”Dependencies not installed” after inworld init

cd your-project-name
npm install

# Init without auto-install, then install manually
inworld init --template llm-to-tts-node --name my-project --skip-install
cd my-project
npm install

​

Template cache issues or outdated template

# Force download fresh template even if cached
inworld init --template llm-to-tts-node --name my-project --force

​

Graph shows unexpected behavior

# Visualize your graph
inworld graph visualize ./graph.ts

# Print graph JSON for inspection
inworld graph variant print ./graph.ts

# Enable verbose logging
export DEBUG=inworld:*
inworld run ./graph.ts '{"input":"test"}'

​

TTS Issues

​

”Voice not found” error

inworld tts list-voices

# Use default voice if specific one fails
inworld tts synthesize "test message"

​

TTS synthesis fails

inworld status
# Verify authentication is valid

# Test with minimal text
inworld tts synthesize "hello"

# Check output directory permissions
ls -la ./

​

Production Issues

​

Deployment Problems

# Check authentication
inworld auth status

❌ Authentication Error

Token Status:
  Inworld Token: eyJraWQiOiJkZWZhdWx0...
  Expires At: 12/20/2024, 10:30:45 AM
  Status: Expired ❌
  
⚠️  Please re-authenticate: inworld login

# Verify graph compiles locally
inworld run ./graph.ts '{"input": "test"}'

❌ Graph Compilation Failed

Error: Missing required configuration
  File: ./graph.ts
  Line: 15
  Issue: Graph ID is required but not specified
  
💡 Fix: Add id to GraphBuilder constructor:
   const graph = new GraphBuilder({ id: 'my-graph-id', ... })

# Check deployment info
inworld deploy ./graph.ts --info

📋 Deployment Information

Graph Details:
  Graph ID: my-graph-id
  Source: ./graph.ts
  Status: Not deployed ❌
  
⚠️  This graph has not been deployed yet.
     Run: inworld deploy ./graph.ts

# Package locally first to debug
inworld deploy ./graph.ts --package-only

❌ Packaging Failed

Validation Errors:
  - Missing API key in environment
  - Graph compilation failed: Syntax error on line 23
  - Dependencies not installed: run 'npm install'
  
💡 Next steps:
   1. Set INWORLD_API_KEY environment variable  
   2. Fix syntax errors in graph.ts
   3. Run 'npm install' to install dependencies

1. Check deployment status: inworld deploy ./graph.ts --info
2. Verify API key is correct: inworld auth status
3. Test with simple input: curl -X POST [endpoint-url] -H "Authorization: Bearer [api-key]" -d '{"input": "test"}'
4. Check Portal logs for errors: Navigate to Portal Logs

1. Review graph complexity with visualization
2. Optimize LLM calls (reduce temperature, limit tokens)
3. Remove unnecessary nodes from execution path
4. Use streaming responses where possible
5. Monitor performance in Portal Dashboards

1. Verify API key is set: echo $INWORLD_API_KEY
2. Check telemetry is enabled (default: ON)
3. Wait 1-2 minutes for data to appear
4. Check Portal time range includes execution time

1. Missing enableRemoteConfig: Set enableRemoteConfig: true in GraphBuilder
2. Graph not registered: Register graph ID in Portal Graph Registry
3. No active rules: Enable targeting rules in Portal
4. Missing API key: Ensure INWORLD_API_KEY environment variable is set

​

Experiment Issues

1. Missing enableRemoteConfig
   // WRONG: Remote config disabled (default)
   const graph = new GraphBuilder({
     id: 'my-graph-id',
     apiKey: process.env.INWORLD_API_KEY
   })
   
   // CORRECT: Enable remote config
   const graph = new GraphBuilder({
     id: 'my-graph-id',
     apiKey: process.env.INWORLD_API_KEY,
     enableRemoteConfig: true  // Required for experiments
   })
   
2. Missing or Invalid UserContext
   • Wrong Command
   • Output (All Users Get Same Variant)

   # WRONG: No targeting key - all users get same variant
   inworld run ./graph.ts '{"input": "hello"}'
   

   {
     "output": {
       "text": "Hello! This is the baseline response.",
       "variant": "baseline"
     },
     "userContext": {
       "targetingKey": "default",
       "attributes": {}
     },
     "warning": "All users assigned to same variant due to default targeting key"
   }
   
3. Graph Not Registered in Portal
   • Verify graph ID matches between CLI and Portal
   • Check Graph Registry shows your graph as “Registered”
   • Ensure variants are uploaded and active
4. Rules Disabled in Portal
   • Check targeting rules are Enabled in Graph Registry
   • Verify traffic distribution adds up to 100%
   • Confirm rule filters match your user attributes

1. Check UserContext: Ensure unique targeting keys are passed
2. Verify Rules: Confirm targeting rules are enabled in Portal
3. Traffic Distribution: Verify percentages add up to 100%
4. Rule Filters: Ensure user attributes match rule criteria

# Test with explicit user context
inworld run ./graph.ts '{
  "input": "test",
  "userContext": {
    "targetingKey": "debug-user-123",
    "attributes": {"tier": "premium", "region": "us"}
  }
}'

{
  "output": {...},
  "experimentInfo": {
    "rule": "Premium Users Test",
    "variantAssignment": "experiment-v1",
    "trafficWeight": 30
  }
}

1. Check variant complexity: Use inworld graph visualize for each variant
2. Compare configurations: Review model parameters, prompt lengths, node counts
3. Monitor metrics: Use Portal dashboards to compare P99 latency across variants
4. Test individually: Run each variant independently to isolate performance issues

​

Quick Diagnostic Commands

# 1. Check CLI version and help
inworld --version
inworld help

# 2. Verify authentication  
inworld status

# 3. Test basic functionality
inworld run ./graph.ts '{"input":"test"}'

# 4. Check project structure
ls -la
cat package.json

# 5. Verify Node.js and npm
node --version
npm --version

​

Environment Setup

​

Set up development environment variables

# Add to ~/.bashrc, ~/.zshrc, etc.
export INWORLD_API_KEY="your-api-key-here"
export DEBUG=inworld:*  # Enable debug logging
export NODE_ENV=development

# Reload shell
source ~/.bashrc  # or ~/.zshrc

​

Project-specific environment

# Create .env file in your project
echo "INWORLD_API_KEY=your-key-here" > .env

# Install dotenv for automatic loading
npm install dotenv

​

Getting More Help

​

CLI Help Commands

inworld help                    # General help
inworld auth --help            # Authentication help  
inworld graph --help           # Graph commands help
inworld tts --help             # TTS commands help

​

Debug Mode

# Enable verbose logging for any command
export DEBUG=inworld:*
inworld [your-command]

​

Before Asking for Help

1. CLI Version: inworld --version
2. Node Version: node --version
3. Operating System: uname -a (Linux/macOS) or Windows version
4. Command that failed: The exact command you ran
5. Error message: Full error output
6. Authentication status: inworld status