Banata

Platform

Troubleshooting

Common Banata integration problems, how to debug them, and the fastest order to check state across sandboxes, tasks, files, and webhooks.

This page focuses on the problems teams hit most often first.

The fastest debugging strategy is usually:

  1. confirm sandbox state
  2. confirm task state
  3. inspect outputs
  4. inspect webhook delivery

Sandbox is not ready yet

If create returns but the sandbox is not usable:

  • use launch() when possible
  • otherwise wait for ready
  • do not send work before readiness

An agent job is taking a long time

Use:

  • promptAsync()
  • taskId
  • webhooks

Do not design long jobs around one open request.

The browser preview opens but you cannot interact

Check:

  • whether the browser is in human or shared control
  • whether a handoff step is active
  • whether you are using the current preview link

A task finished but your app does not know yet

Check:

  • whether a webhook endpoint exists
  • whether the receiver returns 2xx
  • whether task metadata is being passed
  • whether your app stores taskId

Files are missing

Check whether the file was written into /workspace.
That is the right place for important outputs.

Pause and resume behavior looks wrong

Pause is for preserving a workspace.
If the job is complete, end the sandbox instead of keeping it around.

Good debugging order

  1. check sandbox state
  2. check task state
  3. check agent messages
  4. check files and artifacts
  5. check webhook deliveries

Related pages