local-dev-serve-troubleshooting

Common local dev setups

UI fast loop (Vite dev server)

• Start UI:

- npm run dev

• In another terminal, start the Rust server:

- cargo run -- serve --port 8080

Notes:

• lotar serve port must be set with --port (the short -p is reserved for the global --project flag).

- Correct: lotar serve --port 9000 - Also accepted: lotar serve 9000 (positional port; kept for backward compatibility) - Incorrect (sets project, not port): lotar serve -p 9000 - See: docs/help/serve.md

Production-like UI (embedded/static bundle)

• Build web assets:

- npm run build:web

• Build the binary:

- cargo build --release

• Run:

- ./target/release/lotar serve --port 8080

Debugging tips

• If the UI isn’t updating, confirm SSE is connected (GET /api/events). See docs/help/sse.md.
• If you’re working on REST handlers, use docs/help/api-quick-reference.md and keep docs/openapi.json in sync for contract changes.
• When chasing server behavior, enable logs:

- RUST_LOG=debug cargo run -- serve --port 8080

Visual verification (browser + vision)

When validating UI changes, verify in a browser rather than by inspection (see review-handoff):

• Fast poke: lotar serve --port 8080 --open against either the real .tasks/ backlog or a generated demo set (npm run seed:test-tasks -- --serve).
• Vision MCP for quick visual / regression checks: uidiffcheck (reference vs actual), analyzeimage (inspect a captured page), extracttextfromscreenshot (pull labels/terminal text), diagnoseerrorscreenshot (on-screen errors).
• Durable proof: add/extend a Playwright smoke test (smoke-suite-debugging).

Don't capture/paste secrets or PII into screenshots.

Safety

• Treat .env* and local config as sensitive; don’t paste secrets/PII into logs/issues.