Troubleshooting

Docker Compose Won't Start

Symptom: docker compose up fails or services exit immediately.

Port Conflicts

Error: Bind for 0.0.0.0:8000 failed: port is already allocated

Fix: Stop whatever is using the port, or change the port mapping in docker-compose.yml:

# Find what's using port 8000
lsof -i :8000

Out of Memory

Services restart in a loop with OOMKilled status.

Fix: Increase Docker Desktop memory allocation to at least 4GB. VTO with inline inference needs 8GB+.

Services Not Found

Error: service "anyaself-wardrobe" is not found

Fix: Make sure you're running docker compose up from the repository root (new_project/), not from a subdirectory.

Authentication Errors

`401 Unauthorized` on Every Request

Possible causes:

Missing token: Include Authorization: Bearer <token> header
Expired token: JWT tokens have a configured TTL. Re-authenticate via /api/v1/auth/login
Wrong secret: Your AUTH_JWT_SECRET doesn't match between the token issuer and the validating service

Dev quick fix:

# Re-login and get a fresh token
curl -s http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"idToken": "test-user-token"}' | jq '.accessToken'

`403 FORBIDDEN` — "User is not a household member"

You're trying to access a household you haven't joined. Verify:

curl -s http://localhost:8000/api/v1/households \
  -H "Authorization: Bearer $TOKEN" | jq '.[].householdId'

Orchestrator Issues

Agent Returns Stub/Empty Responses

Cause: REQUIRE_VERTEX_AGENT is false (default in dev) — the agent uses a simulated backend.

Fix for real AI responses:

Set REQUIRE_VERTEX_AGENT=true
Configure VERTEX_AGENT_PROJECT_ID, VERTEX_AGENT_LOCATION, VERTEX_AGENT_MODEL
Ensure your GCP service account has aiplatform.user permission

Mission Stuck in `RUNNING` State

Cause: The agent's reasoning loop hit an error. Check orchestrator logs:

docker compose logs orchestrator --tail=50

VTO Issues

VTO Job Returns `FAILED`

Possible causes:

Missing images: Both personImageRef and garmentImageRef must be valid GCS references or URLs
Wrong backend: VTO_INFERENCE_BACKEND is set to simulated (returns stub results) — set to http or inline for real inference
GPU not available: Inline inference requires a GPU. Check logs:

docker compose logs vto --tail=50

Hyperbeam Issues

Session Won't Create

{"error": "UPSTREAM_ERROR", "message": "..."}

Possible causes:

Missing API key: Set HYPERBEAM_API_KEY to a valid Hyperbeam Cloud API key
Rate limited: Hyperbeam has API rate limits. Check the response message field
Network: Verify your machine can reach https://engine.hyperbeam.com

Extension Events Return `401 UNSIGNED_EVENT`

Cause: HYPERBEAM_ENFORCE_EVENT_SIGNATURES=true but events aren't signed.

Fix: Either set HYPERBEAM_ENFORCE_EVENT_SIGNATURES=false for development, or configure HYPERBEAM_EVENT_SIGNING_SECRET and ensure the Hyperbeam extension signs events.

Service-to-Service Communication Failures

`403 FORBIDDEN` — "Missing or invalid internal buy-flow token"

Internal endpoints (cart-ready, failed) require X-Internal-Token header.

Fix: Ensure BUYFLOW_INTERNAL_TOKEN in the API Gateway matches the token sent by the calling service. In dev mode, set REQUIRE_BUYFLOW_INTERNAL_TOKEN=false to skip validation.

`403 FORBIDDEN` — "Missing or invalid internal event token"

Orchestrator internal endpoints (/internal/hyperbeam/events) require X-Internal-Token.

Fix: Ensure ORCHESTRATOR_INTERNAL_TOKEN matches across all services that communicate with the orchestrator (hyperbeam-bridge, artifacts-audit).

Frontend Issues

Frontend Can't Connect to Backend

Symptom: API calls fail with CORS errors or ERR_CONNECTION_REFUSED.

Fix:

Verify the API Gateway is running: curl http://localhost:8000/health
Check CORS is configured: Set CORS_ORIGINS=http://localhost:5173 in the Gateway's env
Verify the frontend's VITE_API_BASE_URL points to http://localhost:8000

Voice WebSocket Disconnects Immediately

Possible causes:

Invalid session token: The session token may have expired (expiresInSeconds TTL)
Missing GCP credentials: Voice proxy needs GOOGLE_APPLICATION_CREDENTIALS for Gemini Live API
Rate limited: Public voice sessions are rate-limited per IP. Wait and retry

Still Stuck?

Check structured logs: All services emit JSON logs with requestId for tracing:
```
docker compose logs --tail=100 | grep "requestId"
```
Check health endpoints: Every service exposes GET /health
Check the Error Reference: See Error Reference for every error code and resolution

Troubleshooting

On this page