Troubleshooting

​

Installation Issues

​

”Permission denied” during installation

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

sudo npm install -g @inworld/runtime

# 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/runtime

​

“inworld-runtime: command not found” after installation

npm list -g @inworld/runtime
# 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-runtime login --force

# Clear cached credentials and retry
inworld-runtime logout
inworld-runtime login

# Check status
inworld-runtime status

​

”Authentication Error” on commands

inworld-runtime status

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

# Wrong workspace? Select correct one
inworld-runtime workspace select

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

​

Multiple workspaces confusion

inworld-runtime workspace select
# Shows interactive list of available workspaces

inworld-runtime 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-runtime serve not starting

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

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

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

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

​

inworld-runtime 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-runtime run ./graph.ts '{"input":"hi"}'

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

​

Project Issues

​

inworld-runtime init creates empty project

# Initialize with the llm-to-tts-node template
inworld-runtime 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-runtime init

cd your-project-name
npm install

# Init without auto-install, then install manually
inworld-runtime 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-runtime init --template llm-to-tts-node --name my-project --force

​

Graph shows unexpected behavior

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

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

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

​

TTS Issues

​

”Voice not found” error

inworld-runtime tts list-voices

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

​

TTS synthesis fails

inworld-runtime status
# Verify authentication is valid

# Test with minimal text
inworld-runtime tts synthesize "hello"

# Check output directory permissions
ls -la ./

​

Production Issues

​

Deployment Problems

# Check authentication
inworld-runtime auth status

❌ Authentication Error

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

# Verify graph compiles locally
inworld-runtime 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-runtime 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-runtime deploy ./graph.ts

# Package locally first to debug
inworld-runtime 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-runtime deploy ./graph.ts --info
2. Verify API key is correct: inworld-runtime 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-runtime 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-runtime 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-runtime 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-runtime --version
inworld-runtime help

# 2. Verify authentication  
inworld-runtime status

# 3. Test basic functionality
inworld-runtime 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-runtime help                    # General help
inworld-runtime auth --help            # Authentication help  
inworld-runtime graph --help           # Graph commands help
inworld-runtime tts --help             # TTS commands help

​

Debug Mode

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

​

Before Asking for Help

1. CLI Version: inworld-runtime --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-runtime status