App problems

Apps run through four tools on the Flux tools server: apps_list, apps_connect, apps_find_actions and apps_execute. Every refusal comes back as a normal tool result with an error code, a message and a retryable flag. Find the code or the symptom below. How apps work is on Use apps.

Status: Shipping

Every apps tool says ability_disabled#

Cause: apps are not switched on for Flux keys on your account yet.

Fix: nothing to fix on your side. The message tells your agent not to retry and to carry on without the tool, which is the right behaviour. The tools start working once apps are switched on for your key.

auth_failed, or the server answers 401#

Cause: the Flux key on your tools server entry is missing, mistyped or revoked.

Fix: the header must read Authorization: Bearer followed by your full Flux key. Make a new key on your keys page if you did not keep the old one. See Tools server problems.

The sign-in link does not work any more#

Cause: a sign-in link can expire before you open it, or stop working once it has been used.

Fix: ask your agent to call apps_connect again for a fresh link, and open it straight away.

If that call is refused because an alias is needed, your first, unfinished sign-in is still counted as a connection on that app. Pass an alias (for example work) to connect anyway, or contact support to clear the unfinished one.

apps_list still shows "pending": true#

Cause: the sign-in has not finished. Either the page is still open, or you closed it before approving access.

Fix:

1. Go back to the sign-in page and finish approving access in the app.
2. Ask your agent to call apps_list again. It shows "connected": true once the app has confirmed.
3. If you closed the page, get a fresh link as above.

The app I connected is not in apps_list#

Cause: you may have connected it on a different Flux account. Connections belong to the account, not to one key, so a key from another account does not see them.

Fix: check which account the key on your tools server entry belongs to on your keys page, then connect the app on that account.

payment_required#

Cause: your account has no paid plan or credit, and today's free app runs are used up. Each apps_execute and each apps_connect uses one. Rarely, the shared free allowance for all accounts runs out first; the answer is the same.

Fix: add credit in Billing and your agent can carry on straight away. Or wait for the next UTC day, when the free runs start again. How many you get is on Use apps.

"Add an account alias"#

Cause: the app already has a connection (finished or not), and connecting again without an alias would replace it.

Fix: pass an alias to apps_connect, such as personal or work. It must be new for that app. Then use that account in your task, for example "post from my work Slack".

"Already has the maximum" accounts#

Cause: one app can hold up to 5 accounts on a Flux account, and this one is full.

Fix: remove an account you no longer need (see disconnecting), then connect again.

rate_limited#

Cause: too many apps calls in a short time on your account. The limits are shared by every key on the account: 120 requests a minute, 600 runs an hour and 2,000 runs a day.

Fix: wait, then retry the same call. The result may carry retry_after_seconds. The daily limit resets at midnight UTC. If a loop in your agent is running actions over and over, stop it and check Activity.

invalid_request on apps_execute#

Cause: the action slug is not in the form the tool accepts, or arguments is not a JSON object. Action slugs are capitals, digits and underscores, such as SLACK_SEND_MESSAGE, and each app has its own.

Fix: call apps_find_actions with the task in plain words, and use the slug and argument names it returns. Do not reuse a slug from memory or from another app.

apps_execute answers "ok": false#

Cause: the tool worked, but the app refused the action. Its reason is in result: often a missing or wrong argument, an action the app does not have, an id that does not exist, or access you did not grant at sign-in.

Fix: read the reason, fix the arguments and run the same step again. If the app says access is missing, connect the account again and approve the access the action needs.

A job ran twice and made duplicates#

Cause: there is no rollback and no duplicate check on the Flux side. Each apps_execute does exactly what it is told.

Fix: have the agent search before it creates, and put a stable id from the source into what it creates. Chain apps shows the pattern.

apps_error#

Cause: finding or running actions failed on the app side.

Fix: rephrase the task for apps_find_actions, or retry apps_execute once. If it keeps failing, contact support with the time of the call.

I want to disconnect an app #

You cannot disconnect an app through Flux yet. Remove Flux's access from the app's own security settings, where most apps list the third-party apps you have connected, or contact support and we will remove the connection for you.

Still stuck?#

The error reference lists every ability error. For anything else, contact support.