Skip to content
Menu

Troubleshooting

What common problems mean and what to ask your bot to do about them.

On this page

Start with a selfcheck

Most problems show up in a selfcheck. Ask your bot to run the installer and the selfcheck for every module, and to list the problems in plain words.

Install problems

  • No module releases are pinned: the template's lock file is empty, so there is nothing to install yet. The bot can still audit what it sees.
  • E_INSTALL_DOWNLOAD: the release file could not be downloaded. The existing install is kept. Try again later or install from a local folder.
  • E_INSTALL_CHECKSUM: the downloaded file does not match its pinned checksum. The file is refused and the existing install is kept.
  • Wrong runtime: modules need Node 24 or Python 3.13 on the bot's computer. The bot reports the mismatch and does not install packages to work around it.

Module errors

Every module answers with the same envelope. When something fails, the errors list carries a code, a plain message and a hint.

  • E_FORBIDDEN_PATH: a module was pointed at the bot's private data folder (/home/box/agent-data), which modules refuse to read. Use a path under /workspace/ambitious or leave the path out.
  • E_NO_KEY: a step needs an AI key that was not passed for that call. Provide the key for the call, or use the command's option that works without one.
  • E_MIGRATION: the database is newer or older than the installed module expects. Run selfcheck, or install the pinned version.
  • E_DB: the database could not be opened or failed its health check. Run selfcheck and read the problem list.
  • E_USAGE: the command was called with conflicting or malformed options. Ask the bot to show the command it ran.
  • E_TOOL (video): a media tool the video module needs is missing on the bot's computer.
  • E_REVIEW_REQUIRED (audit): a report must be marked as reviewed before it can be marked as sent.

Reports are not arriving

  • Check that the weekly routine is turned on and not paused.
  • Check that the connector still has a connection key that has not been revoked. Without one the service refuses every request; create a new key under Bot connection in your dashboard and paste it into the connector.
  • Check that you approved the send. A report waits until the tool call is approved.
  • Check your subscription in the billing portal. Reports are accepted while the subscription is active.
  • After 3 failed attempts the bot stops retrying a report and tells you. Ask it for the error it received.

The audit seems to miss things

Read the visibility section of the audit Page or the report. It lists each kind of information and whether the bot could see it. A guest bot, for example, usually cannot see usage. The audit never guesses about what it could not see.

Dashboard and sign-in

  • The dashboard says it is not set up yet: this site is not connected to accounts or report storage. The example dashboard shows what it will look like.
  • A consultant sees no organizations: the assignment is still pending, was revoked, or was made for a different email.
  • The billing page says there is no subscription: only an organization admin of a subscribed organization can open the portal.

Still stuck

Ask your bot to send feedback to Ambitious with what you tried and the error you saw. Feedback works without a subscription and uses the same approval step as a report.