Troubleshooting

Diagnostic procedures for Escher components — desktop app, backend services, and cloud connections.

---

Health check all services

Run this to get a snapshot of local service health:

for port in 8000 8001 8080 8081 8082; do
  svc=$(case $port in
    8000) echo "asset-store" ;;
    8001) echo "context-engine" ;;
    8080) echo "gateway" ;;
    8081) echo "analysis-agent" ;;
    8082) echo "playbook-agent" ;;
  esac)
  status=$(curl -sf http://localhost:$port/health && echo "✅ OK" || echo "❌ FAILED")
  echo "$svc (port $port): $status"
done

---

Service startup order

Services must start in dependency order. If a dependent service is healthy but the caller can't reach it, check the environment variable pointing to it.

1. SurrealDB        (port 4000) — Asset Store depends on this
2. Asset Store      (port 8000) — Context Engine depends on this
3. Context Engine   (port 8001) — Gateway, Analysis Agent, Playbook Agent depend on this
4. Analysis Agent   (port 8081) — Gateway routes to this
5. Playbook Agent   (port 8082) — Gateway routes to this
6. Gateway          (port 8080) — Desktop app connects here

---

Diagnostic commands

Check ECS service status (production)

# List all services
aws ecs list-services --cluster escher-v2 --region us-west-1

# Check a specific service
aws ecs describe-services \
  --cluster escher-v2 \
  --services escher-gateway \
  --region us-west-1 \
  --query 'services[0].{status:status,running:runningCount,desired:desiredCount,events:events[0:3]}'

Tail service logs (production)

# Gateway logs
aws logs tail /ecs/escher-gateway --follow --region us-west-1

# Analysis Agent logs
aws logs tail /ecs/escher-analysis-agent --follow --region us-west-1

# Context Engine logs
aws logs tail /ecs/escher-context-engine --follow --region us-west-1

Check ALB target health

aws elbv2 describe-target-health \
  --target-group-arn YOUR_TG_ARN \
  --region us-west-1

---

Context Engine diagnostics

Verify a skill is registered

curl -X POST http://localhost:8001/resolve/skill \
  -H "Content-Type: application/json" \
  -d '{
    "query": "detect public s3 buckets",
    "domain": "security",
    "tier": "basic",
    "tenant_id": "your_tenant"
  }'

Check Asset Store → SurrealDB connection

curl http://localhost:8000/health
# {"status":"ok","surreal":"connected"}

# If surreal shows "disconnected":
# Check SURREAL_URL in Asset Store .env
# Verify SurrealDB is running: curl http://localhost:4000/health

Re-run Asset Store schema migration

cd v4-asset-store-go
source venv/bin/activate
asset-store-migrate

---

ADK troubleshooting

Registration partially failed

adk register is atomic per collection. If registration fails mid-way, run it again — it uses upsert semantics and will not duplicate records.

# Check registration state
adk status --agent-id domain.security.exposure --ce-url http://localhost:8001

# Re-register
adk register ./security-exposure-agent/ --ce-url http://localhost:8001

Skill not found in search results

1. Verify registration succeeded: adk list skills --domain security
2. Check the embedding was generated: skills registered before the embedding model was initialised may have null embeddings
3. Re-register to force re-embedding: adk register ./agent/ --force

---

Desktop app diagnostics

Enable verbose logging

In the Escher desktop app, open the developer console:

• macOS: View → Toggle Developer Tools (or Cmd+Option+I)
• Filter for [escher] log prefix

Collect a diagnostic bundle

# macOS — collects app logs, crash reports, and system info
~/Library/Application\ Support/escher/collect-diagnostics.sh

Share the output bundle with Tessell support via your Slack Connect channel.

---

Getting help

Channel	When to use
#escher-support (Slack Connect)	Design Partners — fastest response
GitHub Issues (escher-dbai org)	Bug reports with reproduction steps
Email support@tessell.com	Non-urgent questions, access requests

---

Next steps

• Common Issues — Quick answers to frequent problems
• Docker Compose — Local stack setup
• ECS Deployment — Production infrastructure