Troubleshoot an App

• App events (/api/apps/{id}/events) record platform lifecycle transitions, actions, and errors across the sandbox, deployments, and App deletion.
• App logs (/api/apps/{id}/logs) capture HTTP request logs, console.* output, uncaught exceptions, bundler errors, and runtime transitions from both the development sandbox and production.

Inspect platform state with App events

curl "https://api.judt.ai/api/apps/$APP_ID/events?kind=error,blocked&limit=20" \
  -H "Authorization: Bearer $JUDT_API_KEY"

{
  "id": "evt_7mK2pQ9xRtV4nW6sLc3ZbY8j",
  "app_id": "app_8fK2mQ7xRtV3nW9pLc4ZbY1s",
  "category": "deployment",
  "kind": "error",
  "subject": "dep_4hN8vX2kPq6TmR1wLs9CdF3j",
  "code": "build_failed",
  "message": "npm run build exited with code 1",
  "detail": "src/index.ts(14,5): error TS2322: Type 'number' is not assignable to type 'string'.",
  "created_at": "2026-10-15T20:40:00.000Z"
}

Filter App events

Inspect code execution with App logs

curl "https://api.judt.ai/api/apps/$APP_ID/logs?environment=production&level=warn,error&limit=50" \
  -H "Authorization: Bearer $JUDT_API_KEY"

{
  "id": "LOG_ID",
  "created_at": "2026-10-15T20:42:11.304Z",
  "environment": "production",
  "source": "app",
  "level": "error",
  "event": "exception",
  "message": "TypeError: Cannot read properties of undefined (reading 'id')",
  "request": {
    "method": "GET",
    "path": "/api/items",
    "host": "customer-portal.judt.dev",
    "status": 500,
    "duration_ms": 12
  },
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "attributes": {
    "error.type": "TypeError"
  }
}

Filter App logs

Log sources and notable event names

Common troubleshooting scenarios

1. An HTTP request to the App returns 500

1. Find the failing request in the logs:
   curl "https://api.judt.ai/api/apps/$APP_ID/logs?environment=production&source=request,app&level=error" \
     -H "Authorization: Bearer $JUDT_API_KEY"
   
2. Copy the trace_id from the failing log entry.
3. Fetch every log line from that request in chronological order:
   curl "https://api.judt.ai/api/apps/$APP_ID/logs?trace_id=TRACE_ID&sort=created_at" \
     -H "Authorization: Bearer $JUDT_API_KEY"
   
   Replace TRACE_ID with the 32-character hex trace_id.

2. POST /api/apps/{id}/preview returns 422 preview_failed

1. Read error.detail in the 422 response body for the compiler output.
2. You can also list the dev server’s log entries. A failed build has event set to dev.build_failed:
   curl "https://api.judt.ai/api/apps/$APP_ID/logs?environment=development&source=dev_server" \
     -H "Authorization: Bearer $JUDT_API_KEY"
   

3. POST /api/apps/{id}/deployments fails

1. Read the error in the response. For a deployment that started, inspect error.code and error.message on the Deployment object (GET /api/apps/{id}/deployments/{deployment_id}).
2. Query the events for that deployment ID to see the exact build or migration output:
   curl "https://api.judt.ai/api/apps/$APP_ID/events?subject=$DEPLOYMENT_ID" \
     -H "Authorization: Bearer $JUDT_API_KEY"
   
3. Check the deployment logs:
   curl "https://api.judt.ai/api/apps/$APP_ID/logs?source=deployment" \
     -H "Authorization: Bearer $JUDT_API_KEY"
   

4. A Secret change is not visible in the App

• In the sandbox: The dev server of a running sandbox gets a changed Secret at once. Commands do not get Secrets, so read the Secret from the App’s code on the dev server.
• In production: Changes to Secrets take effect on the next deployment. Call POST /api/apps/{id}/deployments to publish a new deployment with the updated Secret values.

Next steps

• Learn how deployments and rollbacks work in Publish and unpublish an App.
• Check API status codes and retry rules in Errors.