| name | troubleshoot |
| description | Troubleshoots common issues. Covers CDK deploy failures, Docker build errors, Lambda agent issues, test failures, and OpenClaw compatibility. Use when encountering errors during development or deployment. |
| argument-hint | [error description] |
| allowed-tools | Read, Bash, Glob, Grep |
Troubleshooting
Problem to investigate: $ARGUMENTS
Full references:
Common Issues & Solutions
CDK / Synth
| Problem | Cause | Solution |
|---|
Cannot find asset during cdk synth | packages/web/dist/ missing | Run cd packages/web && npx vite build first |
CDK Bootstrap version mismatch | Outdated bootstrap | Run cdk bootstrap |
ROLLBACK_FAILED on SecretsStack | AwsCustomResource partial failure | aws cloudformation delete-stack --stack-name SecretsStack --deletion-mode FORCE_DELETE_STACK, then redeploy |
ECR repository already exists | CDK trying to create existing repo | Use --force delete or Repository.fromRepositoryName() |
| Cross-stack export removal error | Stack import in use | Use --exclusively flag + SSM decoupling pattern |
Docker Build
| Problem | Cause | Solution |
|---|
TS error with openclaw dynamic import | Static analysis of dynamic path | Use variable path: const mod = await import(/* @vite-ignore */ path) |
OCI manifest push error | Default buildx provenance | Add --provenance=false flag to docker buildx build |
npm ci fails (husky postinstall) | prepare script runs in container | npm pkg delete scripts.prepare && npm ci |
Lambda Agent
| Problem | Cause | Solution |
|---|
Cannot find package | Package installed globally, not in LAMBDA_TASK_ROOT | Install in $LAMBDA_TASK_ROOT, not /usr/local |
exports map resolution failure | Node ESM named exports | Use file:// URL import: import(\file://${path}`)` |
| Bedrock discovery timeout (56s) | Auto-discovery scans all regions | Set bedrockDiscovery.enabled: false in OpenClaw config |
extensionAPI not found | Not in exports map | Use file:// URL: import(\file://${ocRoot}/dist/extensionAPI.js`)` |
OpenClaw Compatibility
| Problem | Cause | Solution |
|---|
| v2026.2.14 breaks: scope error | Default-deny scope system, device pairing required | Pin to v2026.2.13 (fastest compatible) |
operator.write stripped | Missing device pairing in v2026.2.14+ | Use v2026.2.13 or implement device pairing |
device field validation fails | Empty publicKey/signature strings | Omit device field entirely (it's Optional) |
client.mode: "operator" invalid | Not a valid Literal type | Use "backend" or "node" |
Tests
| Problem | Cause | Solution |
|---|
vi.mock variable not in scope | Hoisting moves mock above variable declaration | Use vi.hoisted() for variables referenced in mocks |
| E2E tests run with unit tests | Default vitest include matches all .test.ts | Exclude **/*.e2e.test.ts in vitest.config.ts |
workspace:* not resolved | pnpm syntax used in npm workspace | Use "*" for workspace dependencies |
AWS / IAM
| Problem | Cause | Solution |
| -------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------- | ---------------------------------- |
| launchType + capacityProviderStrategy conflict | Cannot specify both in RunTask | Remove launchType, use capacityProviderStrategy only |
| Lambda env var {{resolve:ssm-secure:...}} fails | Not supported for Lambda env vars | Pass SSM path as env var, resolve at runtime via resolveSecrets() |
| ECS Task new secret inaccessible | Execution role not updated | Add ssm:GetParameters to execution role policy |
| Empty env vars from .env | export $(cat .env | xargs) silently sets empty | Verify with ${#VAR} length check |
