Troubleshooting ​

Common issues and how to fix them.

Startup Issues ​

"Docker is not installed" from ./start.sh ​

Install Docker with the compose plugin:

bash
# https://docs.docker.com/engine/install/

"npm is not installed" from ./start.sh ​

Install Node.js (includes npm):

bash
# https://nodejs.org/

Frontend build fails ​

bash
cd frontend
rm -rf node_modules
npm install
npm run build

Or skip the build:

bash
./start.sh --skip-build

Port 8000 already in use ​

bash
lsof -ti:8000 | xargs kill
# Or: SUITCASE_PORT=8080 in .env

Containers won't start ​

bash
docker compose down
docker compose up --build -d
docker compose logs -f

LLM Connection Issues ​

"LLM request failed with HTTP 401" ​

Your API key is missing or invalid. Enter it in the Setup dashboard → LLM card.

"LLM request failed — connection refused" ​

The LLM endpoint is not reachable. Check:

  • LM Studio: local server is running (Developer tab → Start Server)
  • Ollama: ollama list shows your models, ollama serve is running
  • Custom endpoint: the URL is correct

Verification fails ​

Recheck the provider mode, base URL, model name, and API key in the Setup dashboard. Click Save and verify to retry.

OpenAI mode shows wrong defaults ​

If the Setup UI shows stale values (e.g. mock-model), the persisted config in the database may be from a previous test environment. Clear it:

bash
docker exec suitcase-web python3 -c "
import sqlite3, os
db = sqlite3.connect(os.environ.get('AUTOCAREER_DB_PATH','/data/applications.db'))
db.execute('DELETE FROM llm_configs')
db.commit()
"

Then refresh the page and reconfigure.

Powers ​

Power shows missing binaries ​

Toggle the power ON — it auto-runs apt-get install for missing packages. The install status is shown in the card.

Power requires a token ​

Powers that need tokens (Discord, Telegram, Brave, GitHub, Restic) show inline password fields. Type the value and click Save.

Power shows "configured" but binaries are missing ​

Click the Why? button for exact diagnostics. Some binaries (Playwright, Chromium) require manual installation beyond apt-get.

Pulse ​

Pulse interval stuck ​

The pulse interval is configurable from the Setup dashboard → Pulse card. The dropdown sets SUITCASE_PULSE_INTERVAL. Set to 0 to disable. Restart the containers after changing:

bash
docker compose restart

Database Issues ​

"no such table" or corrupted database ​

bash
docker compose down
docker volume rm suitcase-data
docker compose up -d

Reset database from the UI ​

Admin console → Danger Zone → Reset database → Type RESET → Confirm. Clears all career data but preserves .env and LLM settings.

Still Stuck? ​

  1. Check logs: ./start.sh --logs
  2. Test LLM directly: curl http://127.0.0.1:8000/api/health/llm
  3. Check power status: curl http://127.0.0.1:8000/api/powers/status
  4. Open an issue with error logs (redact API keys)

Your private career copilot.