Troubleshooting

​

Installation Issues

​

”Permission denied” during installation

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

​

“inworld: command not found” after installation

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

​

Node.js version issues

node --version
# Must be v18 or higher

​

Authentication Issues

​

Login opens browser but fails

inworld login --force

​

”Authentication Error” on commands

inworld status

​

Multiple workspaces confusion

inworld workspace select
# Shows interactive list of available workspaces

​

Local Development Issues

​

”Graph compilation failed”

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

​

“Module not found” errors

# In your project directory
npm install

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

​

inworld serve not starting

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

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

​

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"

​

Project Issues

​

inworld init creates empty project

# List available templates
inworld init --list-templates

# Use specific template
inworld init --template llm_tts --name my-project

​

”Dependencies not installed” after inworld init

cd your-project-name
npm install

​

Graph shows unexpected behavior

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

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

​

TTS Issues

​

”Voice not found” error

inworld tts list-voices

​

TTS synthesis fails

inworld status
# Verify authentication is valid

​

Production Issues

​

Deployment Problems

# Check authentication
inworld auth status

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

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

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

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
   Copy

   // 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)

   Copy

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

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

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