Troubleshooting

Common issues and how to fix them.

LLM Connection Issues

"LLM request failed with HTTP 401"

Your API key is missing or invalid. Check:

• The API key is entered correctly in the setup wizard
• For LM Studio: no API key is needed by default (leave blank or use lm-studio)
• For Ollama: any value works (ollama is fine)
• For cloud providers: verify the key is active in your provider dashboard

"LLM request failed — connection refused"

The LLM endpoint is not reachable. Check:

• LM Studio: the local server is running (Developer tab → Start Server)
• Ollama: ollama list shows your models, ollama serve is running
• Custom endpoint: the URL is correct and the server is running
• Try curl http://127.0.0.1:1234/v1/models to test directly

"Model not found" or model not listed

The model name doesn't match what your endpoint expects. Check:

• LM Studio: the model filename in the Models tab (e.g., gemma-4-26B-A4B-it-UD-IQ4_XS.gguf)
• Ollama: ollama list for exact model names
• OpenAI: use gpt-4o, gpt-4o-mini, etc.
• Anthropic: use the full model ID like claude-sonnet-4-20250514

LLM verification succeeds but chat times out

The model may be too slow for the default timeout. Try:

1. Set LLM_TIMEOUT_SECONDS=120 in .env
2. Use a smaller/faster model
3. For large local models (>20B), the first response can take 15-30 seconds

"Suitcase wants to chat" Button Not Appearing

This happens when setup isn't fully complete. Check the admin console — all required items (Profile, Resume, LLM) must show Complete.

If they are complete but the button still doesn't appear, try:

1. Refresh the page
2. Clear browser cache and session storage
3. Re-verify the LLM endpoint from the admin console

Discord Bot Not Responding

1. Verify DISCORD_ENABLED=true in .env
2. Check the bot token is correct
3. Confirm your user ID is DISCORD_TARGET_USER_ID
4. Make sure the bot is invited to a server you're in
5. Check the server logs: tail -f /tmp/suitcase-server.log
6. In the admin console, the Synax Runtime must be running

Database Issues

"no such table" or corrupted database

# Backup and reset
cp app/data/applications.db app/data/applications.db.bak
rm app/data/applications.db
# Restart the server — a fresh DB will be created

Reset database from the UI

Admin console → Controls → Reset database → Confirm reset. This clears all data and reloads the page.

Frontend Build Issues

TypeScript errors during build

cd frontend
rm -rf node_modules
npm install
npm run build

Port already in use

# Find and kill the process on port 8000
lsof -ti:8000 | xargs kill
# Or on macOS/Linux
kill $(lsof -t -i:8000)

Still Stuck?

1. Check the server logs: tail -f /tmp/suitcase-server.log
2. Run the smoke test: bash scripts/smoke_test.sh
3. Check LLM health directly: curl http://127.0.0.1:8000/api/health/llm
4. Open an issue with the error message and your configuration (redact API keys)