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 → Model connection card.

"LLM request failed — connection refused" ​

The custom 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 ​

For provider API-key mode, recheck provider, model, and API key. For custom endpoint mode, recheck compatibility mode, base URL, model name, and API key. Click save again 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.