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

# Troubleshooting

> Common issues and solutions for Lua CLI

## Common Errors

### Authentication Errors

<AccordionGroup>
  <Accordion title="No API key found">
    **Error:**

    ```
    ❌ No API key found. Run `lua auth configure` first.
    ```

    **Cause**: You haven't set up authentication yet.

    **Solution**:

    ```bash theme={null}
    lua auth configure
    ```

    Choose authentication method and follow prompts.
  </Accordion>

  <Accordion title="Invalid API key">
    **Error:**

    ```
    ❌ API key validation failed
    ```

    **Causes**:

    * Key was revoked
    * Key was copied incorrectly
    * Extra spaces in key

    **Solutions**:

    1. Verify you copied the complete key
    2. Remove any extra spaces
    3. Generate new key via email method:
       ```bash theme={null}
       lua auth configure
       ```
  </Accordion>

  <Accordion title="OTP not received">
    **Problem**: Email OTP code not received

    **Solutions**:

    1. Check spam/junk folder
    2. Wait 5 minutes (can be delayed)
    3. Try again with `lua auth configure`
    4. Use API Key method if available
  </Accordion>
</AccordionGroup>

### Project Initialization Errors

<AccordionGroup>
  <Accordion title="No lua.skill.yaml found">
    **Error:**

    ```
    ❌ No lua.skill.yaml found. Please run this command from a skill directory.
    ```

    **Cause**: You're not in a skill project directory.

    **Solution**:

    1. Navigate to your skill directory:
       ```bash theme={null}
       cd my-skill
       ```
    2. Or initialize a new project:
       ```bash theme={null}
       lua init
       ```
  </Accordion>

  <Accordion title="Directory not empty">
    **Error:**

    ```
    ❌ Directory is not empty. Please use an empty directory.
    ```

    **Cause**: `lua init` requires an empty directory.

    **Solution**:

    ```bash theme={null}
    mkdir my-new-skill
    cd my-new-skill
    lua init
    ```
  </Accordion>

  <Accordion title="Permission denied">
    **Error:**

    ```
    EACCES: permission denied
    ```

    **Solutions**:

    * Check directory permissions
    * Don't use sudo (creates permission issues later)
    * Use a directory you own:
      ```bash theme={null}
      cd ~/projects
      mkdir my-skill
      cd my-skill
      lua init
      ```
  </Accordion>
</AccordionGroup>

### Compilation Errors

<AccordionGroup>
  <Accordion title="No index.ts found">
    **Error:**

    ```
    ❌ No index.ts found in current directory or src/ directory
    ```

    **Cause**: Missing main skill file.

    **Solution**: Create `src/index.ts`:

    ```typescript theme={null}
    import { LuaSkill } from "lua-cli";

    const skill = new LuaSkill({
      name: "my-skill",
      description: "My skill description",
      context: "How to use this skill",
      tools: []
    });
    ```
  </Accordion>

  <Accordion title="TypeScript compilation error">
    **Error:**

    ```
    ❌ Compilation failed:
    src/tools/MyTool.ts:10:5 - error TS2322: Type 'string' is not assignable to type 'number'.
    ```

    **Cause**: TypeScript type error in your code.

    **Solution**: Fix the specific error mentioned:

    ```typescript theme={null}
    // Error at line 10
    const age: number = "25";  // ❌ Wrong type
    const age: number = 25;    // ✅ Correct
    ```
  </Accordion>

  <Accordion title="Cannot find module">
    **Error:**

    ```
    ❌ Cannot find module 'lua-cli'
    ```

    **Cause**: Dependencies not installed.

    **Solution**:

    <CodeGroup>
      ```bash npm theme={null}
      npm install
      ```

      ```bash yarn theme={null}
      yarn install
      ```

      ```bash pnpm theme={null}
      pnpm install
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Tool name invalid">
    **Error:**

    ```
    ❌ Tool names can only contain alphanumeric characters, hyphens (-), and underscores (_).
    ```

    **Cause**: Tool name contains invalid characters.

    **Solution**: Fix tool name:

    ```typescript theme={null}
    // ❌ Invalid
    name = "get weather";    // Spaces
    name = "get.weather";    // Dots
    name = "get@weather";    // Special chars

    // ✅ Valid
    name = "get_weather";
    name = "get-weather";
    name = "getWeather";
    ```
  </Accordion>
</AccordionGroup>

### Version Management Errors

<AccordionGroup>
  <Accordion title="Version already exists">
    **Error:**

    ```
    ❌ Version 1.0.0 already exists on the server
    ```

    **Cause**: You've already pushed this version number.

    **Solution**: Increment the version number in `lua.skill.yaml` (this is the only field you should manually edit):

    ```yaml theme={null}
    skills:
      - name: my-skill
        version: 1.0.1  # Increment this
    ```

    Then push again:

    ```bash theme={null}
    lua push
    ```
  </Accordion>

  <Accordion title="Version mismatch">
    **Error:**

    ```
    ❌ Version mismatch: config has 1.0.1, deploy.json has 1.0.0
    ```

    **Cause**: Changed version but didn't recompile.

    **Solution**: Recompile after version change:

    ```bash theme={null}
    lua compile
    lua push
    ```
  </Accordion>
</AccordionGroup>

### Sync Errors

<AccordionGroup>
  <Accordion title="Drift detected during compile">
    **Message:**

    ```
    ⚠️  Drift detected in: name, persona
    ```

    **Cause**: Server has different agent configuration than your local code. This happens when someone updates the agent from the admin dashboard.

    **Solutions**:

    1. **Run sync**: Use `lua sync` to review and resolve drift interactively
    2. **Auto-accept**: Use `lua sync --accept` to automatically update local from server
    3. **Auto-push**: Use `lua sync --push` to push local changes to server

    **Note**: By default, `lua compile` does NOT check for drift. Use `lua compile --sync` to enable drift detection during compilation.

    **To see the diff**:

    ```bash theme={null}
    lua sync
    ```
  </Accordion>

  <Accordion title="No persona in local code">
    **Message:**

    ```
    💻 Local (code):
    (no persona in code)
    ```

    **Cause**: The `LuaAgent` configuration is missing or has an empty name.

    **Solutions**:

    1. Ensure your `src/index.ts` has a valid LuaAgent:
       ```typescript theme={null}
       const agent = new LuaAgent({
         name: "my-agent",  // Must not be empty!
         persona: "...",
         // ...
       });
       ```
    2. Check for TypeScript compilation errors
  </Accordion>

  <Accordion title="Network error during sync">
    **Problem**: Sync silently fails or shows no drift when there should be.

    **Cause**: Network issues when fetching server state.

    **Solutions**:

    1. Check internet connection
    2. Verify API key is valid: `lua auth key`
    3. Try again: `lua sync`
  </Accordion>
</AccordionGroup>

### Dev Mode Errors

<AccordionGroup>
  <Accordion title="Port already in use">
    **Error:**

    ```
    ❌ EADDRINUSE: address already in use :::3000
    ```

    **Cause**: Port 3000 is being used by another process.

    **Solutions**:

    1. Stop the other process
    2. Or kill process on port 3000:
       ```bash theme={null}
       # macOS/Linux
       lsof -ti:3000 | xargs kill -9

       # Windows
       netstat -ano | findstr :3000
       taskkill /PID <PID> /F
       ```
  </Accordion>

  <Accordion title="Skill not found in sandbox">
    **Error:**

    ```
    💡 The skill doesn't exist on the server.
    Please run "lua push" first to deploy your skill.
    ```

    **Cause**: Skill hasn't been pushed to server yet.

    **Solution**:

    ```bash theme={null}
    lua push  # Push first
    lua chat  # Then test in sandbox mode
    ```
  </Accordion>

  <Accordion title="Changes not reflected in chat">
    **Problem**: Local changes not showing in sandbox mode.

    **Solutions**:

    1. Verify file is in `src/` directory
    2. Check file is actually saved
    3. Ensure you selected "Sandbox" mode in `lua chat`
    4. Check for compilation errors
    5. Try again:
       ```bash theme={null}
       lua chat  # Will recompile and push to sandbox
       ```
  </Accordion>
</AccordionGroup>

### Deployment Errors

<AccordionGroup>
  <Accordion title="No versions available">
    **Error:**

    ```
    ❌ No versions available to deploy
    ```

    **Cause**: You haven't pushed any versions yet.

    **Solution**:

    ```bash theme={null}
    lua push  # Push a version first
    lua deploy
    ```
  </Accordion>

  <Accordion title="Deploy failed">
    **Error:**

    ```
    ❌ Deployment failed: [error message]
    ```

    **Solutions**:

    1. Check API key is valid
    2. Verify you have deploy permissions
    3. Check network connection
    4. Try again - might be temporary server issue
  </Accordion>
</AccordionGroup>

## Debugging Skills at Runtime

When your tool returns unexpected data or you're unsure why a skill is behaving incorrectly, use this workflow.

<AccordionGroup>
  <Accordion title="Tool returns unexpected shape or undefined fields">
    **Symptoms:**

    * Field is `undefined` when you expected a value
    * `results.data` is undefined
    * `results.count` is undefined
    * Properties like `entry.title` return undefined

    **The fix — log before you transform:**

    ```typescript theme={null}
    async execute(input: any) {
      const results = await Data.search('articles', input.query);
      
      // Add this FIRST, before any mapping
      console.log('Raw result:', JSON.stringify(results, null, 2));
      
      // Then push and check logs:
      // lua logs --type skill --limit 5
    }
    ```

    **Common causes:**

    * Using `results.data` after `Data.search` — search returns a flat array, not `{ data: [...] }`
    * Using `results.count` after `Data.search` — use `results.length`
    * Using `entry.title` after `Data.get` — get entries are not proxied, use `entry.data.title`
    * Using `results.data` after `Products.search` — use `results.products` or iterate directly

    See the [Return Shape Reference](/api/data#return-shape-reference) and [Debugging guide](/cli/debugging).
  </Accordion>

  <Accordion title="5-step debug loop">
    1. Add `console.log('result:', JSON.stringify(result, null, 2))` to the suspicious spot
    2. Run `lua push` (or use `lua chat` sandbox mode without pushing)
    3. Send ONE test message: `lua chat -m "your test query"`
    4. Run `lua logs --type skill --limit 10` — find your log entry
    5. Read the actual shape, fix code once, verify

    **Don't deploy 5 times trying to patch blind.** Log first, deploy once.

    [Full debugging guide →](/cli/debugging)
  </Accordion>

  <Accordion title="How to check logs for a specific tool">
    ```bash theme={null}
    # All skill logs (most recent)
    lua logs --type skill --limit 20

    # Filter to a specific skill
    lua logs --type skill --name my-skill-name --limit 10

    # JSON output (for parsing)
    lua logs --type skill --json

    # Other component types
    lua logs --type job --name daily-report --limit 5
    lua logs --type webhook --name stripe --limit 10
    lua logs --type preprocessor --limit 20
    ```

    Your `console.log()` output appears in the log message body under `🔍 DEBUG` entries.
  </Accordion>
</AccordionGroup>

## Platform-Specific Issues

### macOS

<AccordionGroup>
  <Accordion title="Keychain access denied">
    **Error**: Permission denied accessing keychain

    **Solution**: Grant Terminal/iTerm access:

    1. System Preferences → Security & Privacy
    2. Privacy → Automation
    3. Enable Terminal for Keychain Access
    4. Restart terminal
  </Accordion>

  <Accordion title="Command not found: lua">
    **Cause**: CLI not in PATH

    **Solutions**:

    1. Reinstall globally:
       ```bash theme={null}
       npm install -g lua-cli
       ```
    2. Or use npx:
       ```bash theme={null}
       npx lua-cli [command]
       ```
  </Accordion>
</AccordionGroup>

### Windows

<AccordionGroup>
  <Accordion title="PowerShell execution policy">
    **Error**: Script execution disabled

    **Solution**: Enable script execution:

    ```powershell theme={null}
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```
  </Accordion>

  <Accordion title="Path too long">
    **Error**: `ENAMETOOLONG`

    **Solution**: Use shorter directory paths:

    ```bash theme={null}
    # Instead of
    C:\Users\YourName\Documents\Projects\MyCompany\Skills\my-skill

    # Use
    C:\projects\my-skill
    ```
  </Accordion>
</AccordionGroup>

### Linux

<AccordionGroup>
  <Accordion title="libsecret not found">
    **Error**: Cannot find libsecret

    **Solution**: Install libsecret:

    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt-get install libsecret-1-dev

    # Fedora/RHEL
    sudo dnf install libsecret-devel

    # Arch
    sudo pacman -S libsecret
    ```
  </Accordion>

  <Accordion title="EACCES: permission denied">
    **Error**: Permission denied on global install

    **Solution**: Configure npm to install globally without sudo:

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
    source ~/.bashrc
    npm install -g lua-cli
    ```
  </Accordion>
</AccordionGroup>

## Node.js Issues

<AccordionGroup>
  <Accordion title="Node version too old">
    **Error**: Requires Node.js >= 16.0.0

    **Solution**: Update Node.js:

    1. Visit [https://nodejs.org](https://nodejs.org)
    2. Download LTS version
    3. Or use nvm:
       ```bash theme={null}
       nvm install --lts
       nvm use --lts
       ```
  </Accordion>

  <Accordion title="npm WARN deprecated">
    **Warning**: Package deprecated warnings

    **Solution**: Usually safe to ignore deprecated warnings from dependencies. Update if issues occur:

    ```bash theme={null}
    npm update
    ```
  </Accordion>

  <Accordion title="Dependency conflicts">
    **Error**: Conflicting peer dependencies

    **Solution**: Clear cache and reinstall:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>
</AccordionGroup>

## Network Issues

<AccordionGroup>
  <Accordion title="Connection timeout">
    **Error**: `ETIMEDOUT` or `ECONNREFUSED`

    **Solutions**:

    1. Check internet connection
    2. Check if behind firewall/proxy
    3. Try again - might be temporary
    4. Check server status
  </Accordion>

  <Accordion title="SSL certificate error">
    **Error**: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`

    **Solutions**:

    1. Check system date/time is correct
    2. Update CA certificates
    3. If behind corporate proxy, may need proxy config
  </Accordion>

  <Accordion title="Corporate proxy">
    **Problem**: Behind corporate proxy

    **Solution**: Configure npm proxy:

    ```bash theme={null}
    npm config set proxy http://proxy.company.com:8080
    npm config set https-proxy http://proxy.company.com:8080
    ```
  </Accordion>
</AccordionGroup>

## Environment Variable Issues

<AccordionGroup>
  <Accordion title="Variable not found">
    **Problem**: `env('MY_VAR')` returns undefined

    **Solutions**:

    1. Check spelling in `.env` file:
       ```bash theme={null}
       # .env
       MY_VAR=value  # Correct spelling
       ```
    2. Ensure `.env` is in project root
    3. Restart command (variables loaded at startup)
    4. Check `lua.skill.yaml`:
       ```yaml theme={null}
       skill:
         env:
           MY_VAR: value
       ```
  </Accordion>

  <Accordion title="Changes not taking effect">
    **Problem**: Updated `.env` but changes not visible

    **Solution**: Restart the CLI command:

    ```bash theme={null}
    # Stop current process (Ctrl+C)
    lua chat  # Start again
    ```

    Or manage variables with:

    ```bash theme={null}
    lua env
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

### Diagnostic Information

When reporting issues, include:

```bash theme={null}
# CLI version
lua --version

# Node version
node --version

# npm version
npm --version

# Operating system
uname -a  # macOS/Linux
ver       # Windows

# Error message
# Copy full error from terminal
```

### Support Channels

<CardGroup cols={3}>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Get real-time help from the community
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Search these docs first
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@lua.ai">
    Contact support team
  </Card>
</CardGroup>

## Prevention Tips

<AccordionGroup>
  <Accordion title="Keep CLI Updated">
    ```bash theme={null}
    npm update -g lua-cli
    ```

    Or check current version:

    ```bash theme={null}
    lua --version
    ```
  </Accordion>

  <Accordion title="Commit lua.skill.yaml">
    Always commit `lua.skill.yaml` to git:

    ```bash theme={null}
    git add lua.skill.yaml
    git commit -m "Update skill config"
    ```
  </Accordion>

  <Accordion title="Don't Commit .env">
    Add to `.gitignore`:

    ```
    .env
    .env.local
    ```
  </Accordion>

  <Accordion title="Test Before Deploy">
    Always test locally:

    ```bash theme={null}
    lua chat  # Test conversationally (sandbox mode)
    lua test  # Optional: Test specific tools
    lua push  # Push when ready
    lua deploy  # Deploy to production
    ```
  </Accordion>
</AccordionGroup>

## Still Having Issues?

If your issue isn't covered here:

1. **Ask on Discord**: Get real-time help from the community
2. **Email Support**: For urgent issues or account problems

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/SRPEuwCzaD">
    Join other Lua builders for real-time help
  </Card>

  <Card title="Contact Support" icon="life-ring" href="mailto:support@lua.ai">
    [support@lua.ai](mailto:support@lua.ai) - We're here to help!
  </Card>
</CardGroup>