Troubleshooting

Solutions for common issues with Khaos Machine.

Installation Issues

macOS: "App is damaged" or Gatekeeper Warning

If macOS blocks the installer, allow it in System Settings:

1. Open System Settings → Privacy & Security.
2. Scroll down — you should see a message about the blocked installer.
3. Click Open Anyway.

Or bypass from the terminal:

sudo xattr -r -d com.apple.quarantine KhaosFoundation-signed.pkg

Linux: Missing Dependencies

If the .deb install fails with dependency errors:

sudo apt-get install -f

Windows: "Not Recognized" After Install

If khaosd is not recognized after extracting the ZIP:

1. Ensure the extraction directory is on your PATH.
2. Open a new PowerShell window (PATH changes require a restart).
3. Verify: khaosd --version

Daemon Issues

Daemon Won't Start

Check if already running:

ps aux | grep khaosd

Check for port conflicts:

cat ~/.khaos/runtime.json
# Note the port number, then:
lsof -i :PORT_NUMBER

Check logs:

tail -20 ~/.khaos/logs/khaosd.log

Restart the daemon:

# macOS — restart via LaunchAgent
launchctl kickstart -k gui/$(id -u)/studio.khaos.khaosd

# Linux — restart via systemd
systemctl --user restart khaos-wfl

Menu Bar App Not Showing (macOS)

1. Check if the app is running: ps aux | grep "Khaos Machine"
2. Check Console.app — filter by studio.khaos.machine for errors.
3. Check the LaunchAgent:

launchctl print gui/$(id -u)/studio.khaos.khaosd

Stale Socket File

If the workflow daemon crashed, it may leave a stale socket preventing restart:

rm ~/.khaos/wfl.sock
# Then restart the daemon

Analysis Issues

Analysis Fails Immediately

Check your provider configuration:

1. Open Settings in the web dashboard.
2. Verify the correct provider is selected.
3. For cloud providers, verify your API key is entered.

Check the console log:

tail -50 ~/.khaos/logs/khaosd-console.log | grep '"level":"error"'

Analysis Hangs or Times Out

• Cloud providers: check your internet connection and API rate limits.
• Ollama: ensure the Ollama service is running (ollama serve).
• LM Studio: ensure the local server is started in LM Studio.

Large models may take several minutes per scene. Check progress in the Console view.

All Scenes Fail

Common causes:

1. API key expired or invalid — regenerate your key and update in Settings.
2. Rate limiting — wait a few minutes and try again, or switch to a local provider.
3. Model unavailable — verify the model exists: ollama list or check your provider's model page.

Provider-Specific Issues

Ollama

"Connection refused":

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama if not running
ollama serve

Model not found:

# List installed models
ollama list

# Pull a model
ollama pull qwen3:8b

LM Studio

"Unsupported provider type: lmstudio":

Your khaos-tools version is too old. Update to v0.5.30 or later.

"Invalid model identifier":

LM Studio requires the full model ID (e.g., qwen/qwen3-8b), not just the short name. Check installed models:

lms ls

"response_format.type must be json_schema or text":

Update khaos-tools to v0.5.33 or later.

OpenAI

"Incorrect API key provided":

1. Go to platform.openai.com/api-keys.
2. Generate a new key.
3. Update in Khaos Machine Settings.

Rate limit errors:

OpenAI has per-minute rate limits. Reduce batch size or wait before retrying.

Anthropic

"Invalid API key":

1. Go to console.anthropic.com.
2. Generate a new key.
3. Update in Khaos Machine Settings.

Import Issues

Unsupported Format

Khaos Machine supports: .fountain, .fdx, .sbx, .md, .pdf, .txt.

If your format isn't supported, export to Fountain (.fountain) from your screenwriting application.

PDF Import Fails

PDF import requires pdftotext on your system:

# macOS
brew install poppler

# Linux
sudo apt-get install poppler-utils

Encoding Issues

If imported text shows garbled characters, ensure your screenplay file is saved with UTF-8 encoding.

Log Locations

All logs are in ~/.khaos/logs/:

File	Contents
khaosd.log	Daemon HTTP lifecycle
khaosd-console.log	Job progress and errors
khaos-wfl.log	Workflow daemon events
khaos-tui.log	Terminal UI activity
khaos-machine.log	Menu bar app (macOS)

Getting More Help

If your issue isn't covered here, see the FAQ or Contact us.