> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

This guide walks through troubleshooting for common CLI setup and development issues.

## Installation Issues

### "Permission denied" during installation

<Tabs>
  <Tab title="Problem">
    ```bash theme={"system"}
    npm install -g @inworld/runtime
    # Error: EACCES: permission denied
    ```
  </Tab>

  <Tab title="Solution">
    **On macOS/Linux:**

    ```bash theme={"system"}
    sudo npm install -g @inworld/runtime
    ```

    **Alternative (without sudo):**

    ```bash theme={"system"}
    # 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
    ```
  </Tab>
</Tabs>

### "inworld-runtime: command not found" after installation

<Tabs>
  <Tab title="Check Installation">
    ```bash theme={"system"}
    npm list -g @inworld/runtime
    # Should show the installed package
    ```
  </Tab>

  <Tab title="Fix PATH">
    ```bash theme={"system"}
    # 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
    ```
  </Tab>
</Tabs>

### Node.js version issues

<Tabs>
  <Tab title="Check Version">
    ```bash theme={"system"}
    node --version
    # Must be v18 or higher
    ```
  </Tab>

  <Tab title="Upgrade Node.js">
    **Using nvm (recommended):**

    ```bash theme={"system"}
    # 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
    ```

    **Or download from nodejs.org:**
    Visit [nodejs.org](https://nodejs.org) and download the latest LTS version.
  </Tab>
</Tabs>

## Authentication Issues

### Login opens browser but fails

<Tabs>
  <Tab title="Quick Fix">
    ```bash theme={"system"}
    inworld-runtime login --force
    ```
  </Tab>

  <Tab title="If That Doesn't Work">
    ```bash theme={"system"}
    # Clear cached credentials and retry
    inworld-runtime logout
    inworld-runtime login

    # Check status
    inworld-runtime status
    ```
  </Tab>
</Tabs>

### "Authentication Error" on commands

<Tabs>
  <Tab title="Check Status">
    ```bash theme={"system"}
    inworld-runtime status
    ```
  </Tab>

  <Tab title="Common Solutions">
    ```bash theme={"system"}
    # 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
    ```
  </Tab>
</Tabs>

### Multiple workspaces confusion

<Tabs>
  <Tab title="List Workspaces">
    ```bash theme={"system"}
    inworld-runtime workspace select
    # Shows interactive list of available workspaces
    ```
  </Tab>

  <Tab title="Check Current">
    ```bash theme={"system"}
    inworld-runtime status
    # Shows currently active workspace
    ```
  </Tab>
</Tabs>

## Local Development Issues

### "Graph compilation failed"

<Tabs>
  <Tab title="Check Syntax">
    ```bash theme={"system"}
    # Compile TypeScript directly to check for syntax errors
    npx tsc --noEmit ./graph.ts
    ```
  </Tab>

  <Tab title="Common Issues">
    **Missing Graph ID:**

    ```typescript theme={"system"}
    // ❌ 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
    })
    ```

    **Missing Dependencies:**

    ```bash theme={"system"}
    npm install  # Make sure all packages are installed
    ```
  </Tab>
</Tabs>

### "Module not found" errors

<Tabs>
  <Tab title="Install Dependencies">
    ```bash theme={"system"}
    # In your project directory
    npm install

    # Verify package.json exists
    ls -la package.json
    ```
  </Tab>

  <Tab title="Check Import Paths">
    ```typescript theme={"system"}
    // ✅ Correct import
    import { GraphBuilder, LLMChatNode } from '@inworld/runtime';

    // ❌ Wrong import path
    import { GraphBuilder } from 'inworld-runtime';
    ```
  </Tab>
</Tabs>

### `inworld-runtime serve` not starting

<Tabs>
  <Tab title="Check Port Availability">
    ```bash theme={"system"}
    # Default port 3000 in use?
    lsof -i :3000

    # Use different port
    inworld-runtime serve ./graph.ts --port 8080
    ```
  </Tab>

  <Tab title="Check Graph Compilation">
    ```bash theme={"system"}
    # Test graph compilation first
    inworld-runtime run ./graph.ts '{"input":"test"}'

    # If that works, then try serve
    inworld-runtime serve ./graph.ts
    ```
  </Tab>
</Tabs>

### `inworld-runtime run` hangs or times out

<Tabs>
  <Tab title="Check API Key">
    ```bash theme={"system"}
    # Verify API key is set
    echo $INWORLD_API_KEY

    # Or set it for the session
    export INWORLD_API_KEY="your-key-here"
    ```
  </Tab>

  <Tab title="Simplify Input">
    ```bash theme={"system"}
    # 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"}
    }'
    ```
  </Tab>
</Tabs>

## Project Issues

### `inworld-runtime init` creates empty project

<Tabs>
  <Tab title="Use Template">
    ```bash theme={"system"}
    # Initialize with the llm-to-tts-node template
    inworld-runtime init --template llm-to-tts-node --name my-project
    ```
  </Tab>

  <Tab title="Manual Setup">
    ```bash theme={"system"}
    # If template fails, create manually
    mkdir my-project && cd my-project
    npm init -y
    npm install @inworld/runtime

    # Copy example from docs or templates
    ```
  </Tab>
</Tabs>

### "Dependencies not installed" after `inworld-runtime init`

<Tabs>
  <Tab title="Manual Installation">
    ```bash theme={"system"}
    cd your-project-name
    npm install
    ```
  </Tab>

  <Tab title="Skip Auto-Install">
    ```bash theme={"system"}
    # 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
    ```
  </Tab>
</Tabs>

### Template cache issues or outdated template

```bash theme={"system"}
# Force download fresh template even if cached
inworld-runtime init --template llm-to-tts-node --name my-project --force
```

**Note:** The template is cached for 24 hours. Use `--force` to bypass the cache and download the latest version from GitHub.

### Graph shows unexpected behavior

<Tabs>
  <Tab title="Check Graph Structure">
    ```bash theme={"system"}
    # Visualize your graph
    inworld-runtime graph visualize ./graph.ts

    # Print graph JSON for inspection
    inworld-runtime graph variant print ./graph.ts
    ```
  </Tab>

  <Tab title="Enable Debug Logging">
    ```bash theme={"system"}
    # Enable verbose logging
    export DEBUG=inworld:*
    inworld-runtime run ./graph.ts '{"input":"test"}'
    ```
  </Tab>
</Tabs>

## TTS Issues

### "Voice not found" error

<Tabs>
  <Tab title="List Available Voices">
    ```bash theme={"system"}
    inworld-runtime tts list-voices
    ```
  </Tab>

  <Tab title="Use Default Voice">
    ```bash theme={"system"}
    # Use default voice if specific one fails
    inworld-runtime tts synthesize "test message"
    ```
  </Tab>
</Tabs>

### TTS synthesis fails

<Tabs>
  <Tab title="Check API Key">
    ```bash theme={"system"}
    inworld-runtime status
    # Verify authentication is valid
    ```
  </Tab>

  <Tab title="Try Simple Synthesis">
    ```bash theme={"system"}
    # Test with minimal text
    inworld-runtime tts synthesize "hello"

    # Check output directory permissions
    ls -la ./
    ```
  </Tab>
</Tabs>

## Production Issues

### Deployment Problems

**Problem**: "Graph deployment fails"

<Tabs>
  <Tab title="Command">
    ```bash theme={"system"}
    # Check authentication
    inworld-runtime auth status
    ```
  </Tab>

  <Tab title="Possible Output (Token Expired)">
    ```
    ❌ Authentication Error

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

<Tabs>
  <Tab title="Command">
    ```bash theme={"system"}
    # Verify graph compiles locally
    inworld-runtime run ./graph.ts '{"input": "test"}'
    ```
  </Tab>

  <Tab title="Possible Error Output">
    ```
    ❌ 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', ... })
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Command">
    ```bash theme={"system"}
    # Check deployment info
    inworld-runtime deploy ./graph.ts --info
    ```
  </Tab>

  <Tab title="Possible Output (Not Deployed)">
    ```
    📋 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
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Command">
    ```bash theme={"system"}
    # Package locally first to debug
    inworld-runtime deploy ./graph.ts --package-only
    ```
  </Tab>

  <Tab title="Possible Error Output">
    ```
    ❌ 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
    ```
  </Tab>
</Tabs>

**Problem**: "Endpoint not responding after deployment"

**Debug Steps:**

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](/portal/logs)

**Problem**: "High latency after deployment"

**Optimization Steps:**

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](/portal/dashboards)

**Problem**: "Metrics/traces not appearing in Portal"

**Solutions:**

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

**Problem**: "Graph always uses local config instead of variants"

**Check these issues:**

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

**Problem**: "All users getting the same variant despite traffic splits"

**Causes & Solutions:**

1. **Missing enableRemoteConfig**
   ```typescript theme={"system"}
   // 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**

   <Tabs>
     <Tab title="Wrong Command">
       ```bash theme={"system"}
       # WRONG: No targeting key - all users get same variant
       inworld-runtime run ./graph.ts '{"input": "hello"}'
       ```
     </Tab>

     <Tab title="Output (All Users Get Same Variant)">
       ```json theme={"system"}
       {
         "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"
       }
       ```
     </Tab>
   </Tabs>

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

**Problem**: "Users not getting expected variant distribution"

**Debug Steps:**

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

<Tabs>
  <Tab title="Debug Command">
    ```bash theme={"system"}
    # Test with explicit user context
    inworld-runtime run ./graph.ts '{
      "input": "test",
      "userContext": {
        "targetingKey": "debug-user-123",
        "attributes": {"tier": "premium", "region": "us"}
      }
    }'
    ```
  </Tab>

  <Tab title="Check Output">
    ```json theme={"system"}
    {
      "output": {...},
      "experimentInfo": {
        "rule": "Premium Users Test",
        "variantAssignment": "experiment-v1",
        "trafficWeight": 30
      }
    }
    ```
  </Tab>
</Tabs>

**Problem**: "Variant performance differs significantly"

**Debug Steps:**

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

When things go wrong, run these commands to gather diagnostic info:

```bash theme={"system"}
# 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

```bash theme={"system"}
# 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

```bash theme={"system"}
# 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

```bash theme={"system"}
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

```bash theme={"system"}
# Enable verbose logging for any command
export DEBUG=inworld:*
inworld-runtime [your-command]
```

### Before Asking for Help

When reporting issues, please include:

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`

This information helps diagnose issues quickly and effectively.