Skip to main content

​
Common Errors

​
Authentication Errors

Error:
❌ No API key found. Run `lua auth configure` first.
Cause: You haven’t set up authentication yet.Solution:
lua auth configure
Choose authentication method and follow prompts.
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: 
    lua auth configure
Problem: Email OTP code not receivedSolutions:
  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

​
Project Initialization Errors

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: 
    cd my-skill
  2. Or initialize a new project: 
    lua init
Error:
❌ Directory is not empty. Please use an empty directory.
Cause: lua init requires an empty directory.Solution:
mkdir my-new-skill
cd my-new-skill
lua init
Error:
EACCES: permission denied
Solutions:
  • Check directory permissions
  • Don’t use sudo (creates permission issues later)
  • Use a directory you own: 
    cd ~/projects
mkdir my-skill
cd my-skill
lua init

​
Compilation Errors

Error:
❌ No index.ts found in current directory or src/ directory
Cause: Missing main skill file.Solution: Create src/index.ts:
import { LuaSkill } from "lua-cli";

const skill = new LuaSkill({
  name: "my-skill",
  description: "My skill description",
  context: "How to use this skill",
  tools: []
});
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:
// Error at line 10
const age: number = "25";  // ❌ Wrong type
const age: number = 25;    // ✅ Correct
Error:
❌ Cannot find module 'lua-cli'
Cause: Dependencies not installed.Solution:
npm install
Error:
❌ Tool names can only contain alphanumeric characters, hyphens (-), and underscores (_).
Cause: Tool name contains invalid characters.Solution: Fix tool name:
// ❌ Invalid
name = "get weather";    // Spaces
name = "get.weather";    // Dots
name = "get@weather";    // Special chars

// ✅ Valid
name = "get_weather";
name = "get-weather";
name = "getWeather";

​
Version Management Errors

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):
skills:
  - name: my-skill
    version: 1.0.1  # Increment this
Then push again:
lua push
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:
lua compile
lua push

​
Sync Errors

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. Interactive: Choose to update local from server or keep local
  2. Auto-sync: Use lua compile --force-sync to automatically update local
  3. Skip: Use lua compile --no-sync to ignore drift (your next push will overwrite server)
To see the diff:
lua sync
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: 
    const agent = new LuaAgent({
  name: "my-agent",  // Must not be empty!
  persona: "...",
  // ...
});
  2. Check for TypeScript compilation errors
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

​
Dev Mode Errors

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: 
    # macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
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:
lua push  # Push first
lua chat  # Then test in sandbox mode
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: 
    lua chat  # Will recompile and push to sandbox

​
Deployment Errors

Error:
❌ No versions available to deploy
Cause: You haven’t pushed any versions yet.Solution:
lua push  # Push a version first
lua deploy
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

​
Platform-Specific Issues

​
macOS

Error: Permission denied accessing keychainSolution: Grant Terminal/iTerm access:
  1. System Preferences → Security & Privacy
  2. Privacy → Automation
  3. Enable Terminal for Keychain Access
  4. Restart terminal
Cause: CLI not in PATHSolutions:
  1. Reinstall globally: 
    npm install -g lua-cli
  2. Or use npx: 
    npx lua-cli [command]

​
Windows

Error: Script execution disabledSolution: Enable script execution:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Error: ENAMETOOLONGSolution: Use shorter directory paths:
# Instead of
C:\Users\YourName\Documents\Projects\MyCompany\Skills\my-skill

# Use
C:\projects\my-skill

​
Linux

Error: Cannot find libsecretSolution: Install libsecret:
# Ubuntu/Debian
sudo apt-get install libsecret-1-dev

# Fedora/RHEL
sudo dnf install libsecret-devel

# Arch
sudo pacman -S libsecret
Error: Permission denied on global installSolution: Configure npm to install globally without sudo:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g lua-cli

​
Node.js Issues

Error: Requires Node.js >= 16.0.0Solution: Update Node.js:
  1. Visit https://nodejs.org
  2. Download LTS version
  3. Or use nvm: 
    nvm install --lts
nvm use --lts
Warning: Package deprecated warningsSolution: Usually safe to ignore deprecated warnings from dependencies. Update if issues occur:
npm update
Error: Conflicting peer dependenciesSolution: Clear cache and reinstall:
rm -rf node_modules package-lock.json
npm install

​
Network Issues

Error: ETIMEDOUT or ECONNREFUSEDSolutions:
  1. Check internet connection
  2. Check if behind firewall/proxy
  3. Try again - might be temporary
  4. Check server status
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURESolutions:
  1. Check system date/time is correct
  2. Update CA certificates
  3. If behind corporate proxy, may need proxy config
Problem: Behind corporate proxySolution: Configure npm proxy:
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

​
Environment Variable Issues

Problem: env('MY_VAR') returns undefinedSolutions:
  1. Check spelling in .env file: 
    # .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: 
    skill:
  env:
    MY_VAR: value
Problem: Updated .env but changes not visibleSolution: Restart the CLI command:
# Stop current process (Ctrl+C)
lua chat  # Start again
Or manage variables with:
lua env

​
Getting Help

​
Diagnostic Information

When reporting issues, include: 
# 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

Discord Community

Get real-time help from the community

Documentation

Search these docs first

Email Support

Contact support team

​
Prevention Tips

npm update -g lua-cli
Or check current version:
lua --version
Always commit lua.skill.yaml to git:
git add lua.skill.yaml
git commit -m "Update skill config"
Add to .gitignore:
.env
.env.local
Always test locally:
lua chat  # Test conversationally (sandbox mode)
lua test  # Optional: Test specific tools
lua push  # Push when ready
lua deploy  # Deploy to production

​
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

Discord Community

Join other Lua builders for real-time help

Contact Support

[email protected] - We’re here to help!