Common Issues

Answers to the most frequently encountered problems when setting up and using Escher.

---

Desktop app

App won't launch / crashes on startup

1. Check macOS version — Escher requires macOS 13 (Ventura) or later.
2. Check that Xcode Command Line Tools are installed: xcode-select --install
3. If you see a security warning ("app is damaged"), run:

   xattr -cr /Applications/Escher.app

4. Check the crash log in Console.app → Reports.

"Cannot connect to keychain" error

The vault plugin uses the macOS Keychain. Ensure the app has keychain access:

• Open Keychain Access → search for escher
• If an existing entry is locked or corrupted, delete it and re-authenticate

---

Cloud connections

AWS profile shows "Invalid credentials"

1. Verify the profile exists: aws sts get-caller-identity --profile YOUR_PROFILE
2. Ensure the IAM user/role has the required permissions — see AWS Connection
3. If using SSO, re-authenticate: aws sso login --profile YOUR_PROFILE
4. Check that the profile region is set correctly in ~/.aws/config

Estate scan returns 0 resources

• Check that the profile has ec2:Describe*, s3:List*, and iam:List* permissions
• Verify the correct region is configured for the scan
• Try running a manual refresh: Estate → ↻ Refresh

Azure connection fails with "Insufficient privileges"

Ensure the service principal or user account has the Reader role on the target subscription:

az role assignment list --assignee YOUR_EMAIL --subscription YOUR_SUB_ID

---

Backend services

Gateway returns 502 Bad Gateway

The ALB target group health check is failing. Check:

1. ECS service is running: aws ecs describe-services --cluster escher-v2 --services escher-gateway
2. Health check endpoint: GET /q/health should return {"status":"UP"}
3. Security group allows ALB → Gateway on port 8080

Analysis Agent returns "Anthropic API error"

1. Verify ANTHROPIC_API_KEY is set and valid
2. Check rate limits — Anthropic API has per-minute token limits
3. Look at Analysis Agent logs in CloudWatch: /ecs/escher-analysis-agent

Context Engine returns 503

Asset Store may be unhealthy. Check:

curl http://asset-store.escher.internal:8000/health
# Expected: {"status":"ok"}

If unhealthy, check SurrealDB connectivity.

---

ADK

adk register fails with "domain not found"

The classification.domain in your agent.yaml must match a registered domain. List valid domains:

adk list domains --ce-url http://localhost:8001
# Returns: security, compliance, cost, performance, reliability

adk validate reports "missing required field"

Check against the required fields in the agent.yaml Reference. Common misses:

• classification.domain — must be a registered domain
• capabilities[] — at least one entry required
• skills[].skill_id — must follow domain.verb_noun pattern

---

Next steps

• Troubleshooting — Detailed diagnostic steps
• AWS Connection — Fixing IAM permission issues
• Docker Compose — Local stack setup