Runtime

Errors

Every error code, what it means and what to do.

When a tool call fails, it returns isError: true, a message written for a person (safe to show as is, and it says what to do next), and a machine-readable code:

{
  "error": {
    "code": "scan_failed",
    "message": "Fix the 2 security issues before sharing with everyone at Acme.",
    "details": { "issues": ["iss_01", "iss_02"] }
  }
}

Codes

Code	Meaning	What to do
`invalid_request`	A parameter is missing or malformed.	Check the parameters against the tool reference.
`validation_failed`	The values are well formed but not accepted, for example a bad secret name.	Read the message; it names the field.
`unauthenticated`	The token is missing, expired or revoked.	Reconnect the AI tool. See Manage connections.
`forbidden`	Your role does not allow this.	Ask the app's Owner or an admin.
`not_found`	The app, version or item does not exist, or you cannot see it.	Call `list_apps` for the right name or id.
`ambiguous`	A name matched more than one app, person or group. Nothing was changed.	Call again with an id or email.
`slug_taken`	The address is already used by another app or workspace.	Pick another name, or pass `app_id` to update the existing app.
`app_creation_restricted`	Your admin limited who can create new apps in this workspace.	Ask an admin to add you.
`policy_blocked`	A workspace policy blocks this, for example public links are off.	Use another option, or ask an admin.
`guests_not_allowed`	You tried to share with someone outside the company and guests are off.	Ask an admin to allow guests.
`scan_failed`	Blocking security issues are open.	Fix them and redeploy.
`scan_running`	The security scan of the latest version has not finished.	Try again once it has, usually in under a minute.
`request_pending`	An admin already has the same request, for example to list or unlist the app.	Wait for the admin's decision. You get an email.
`team_required`	Sharing with the whole company needs the team the app is listed under, and the workspace has several.	Pick one from `list_teams` and call again with `team`.
`payment_required`	The workspace's 7 free days are over. Deploying and sharing need a plan. Apps already live keep running.	Choose a plan. See Plans.
`connector_not_connected`	The app asked for HubSpot data and the viewer has not connected their own HubSpot account.	Send the viewer to `error.details.connect_url`.
`review_required`	In a company workspace, everyone at the company gets an app through the company directory, and some directory changes need an admin.	Use `submit_to_directory` or `unlist_from_directory`. `share_app` does this for you when you share with the whole company.
`stale_patch`	A newer version was deployed after the AI fix was written.	Ask for a new fix.
`stale_secret`	The secret changed while you were editing it.	Reload and try again.
`too_large`	A file, upload or result is over the limit.	See Limits.
`domain_taken`	Another workspace already owns this company domain.	Ask to join that workspace.
`last_admin`	You tried to demote or remove the only admin.	Make someone else an admin first.
`owns_company_apps`	The person still owns apps in a company workspace.	Transfer them first, or use Offboarding.
`rate_limited`	Too many requests.	Wait the number of seconds in the message.
`internal`	Something went wrong on Inhaus's side.	Try again in a moment. If it keeps happening, email [email protected].

Deploy failures

A failed deploy is not an error code on the call: deploy_app returns status: "failed" with error and build_log_tail. Common causes:

Message	Cause
`Nothing to run: add an index.html ...`	No static entry and no server entry. See Project structure.
`Could not resolve "fs"` (or another Node built-in)	The code or a package needs Node.js. Use web APIs instead.
`A database migration failed: ...` (`migration_failed`)	A SQL file in `migrations/` has an error. The previous version stays live.
`build_gave_up`	The build could not finish after several tries. Deploy again.