Debug a failed connected app tool without broadening access

Locate the first failed boundary

Start with the selected connection and the exact error code. An organization-scope failure differs from inactive authorization, a changed revision, invalid tool metadata or a provider result that did not report success. Read the connection status and retain the saved tool proposal before changing anything. A successful hosted login does not prove the selected tool has the necessary scopes or arguments. Diagnose in boundary order so a permissions problem is not repaired by blindly reconnecting, and a provider outage is not repaired by giving the agent a broader owner credential.

Recheck discovery identity and input shape

Use the tools endpoint under the intended connection to inspect tool_slug, concrete version, input_schema and connection_revision. The route rejects latest and disallows tools from another toolkit or deprecated metadata. A reconnect can invalidate an old revision while leaving the same local connection ID. A request body must contain only arguments, version and connection_revision; custom authentication fields and arbitrary proxy instructions are not accepted. Compare the actual submitted JSON with the discovered schema, including types and required fields, before deciding the provider is broken.

Separate admission rejection from provider execution

Spending policy, arguments above the serialized JSON limit of 100,000 UTF-16 code units or an idempotency conflict can stop an action before the external tool runs. These conditions do not call for another OAuth grant. On the other hand, a provider timeout can leave the action uncertain after submission. Preserve the same operation key and operation ID rather than converting every failure into an automatic retry with a fresh key. The safe next step depends on whether an effect was definitively rejected or may already have happened, not simply on whether the HTTP client received a success response.

Inspect unsuccessful results with their context

The sanitized execution response includes successful, returned data, operation identity and a provider log reference when supplied. An unsuccessful result should be inspected before another action is proposed; it does not universally prove that no partial side effect occurred. Keep the external resource and account context in a private incident record, while avoiding tokens and unrelated customer content. If the result reveals insufficient scope, ask whether the workflow truly needs broader access before reconnecting. If it reveals a malformed argument, prepare the corrected action for fresh approval after resolving the original operation’s outcome.

Reproduce the boundary with a focused fixture

A useful local reproduction fakes the provider metadata or execution response that triggered the failure and asserts the expected API behavior. Include wrong toolkit, stale revision, inactive account, changed arguments under one key and lost response after a known effect. Count provider executions to ensure the recovery does not duplicate work. Once the cause is clear, report the affected boundary, corrected behavior and remaining live uncertainty. Do not claim a production fix based solely on a fake provider success; arrange a narrow owner-authorized check only when that external validation is actually needed.

Keep a minimal incident example

For connection_changed, retain the selected connection and old revision, refresh discovery and show the revised account to the owner. There is no reason to request their password or broaden OAuth scopes first. A synthetic replacement fixture can reproduce the rejection and confirm that the provider execution count remains zero.

Sources & verification

Reviewed against current checked-in Lupin routes, shared contracts and official provider references. No live calls, OAuth authorizations, app actions or purchases were performed.

• Lupin connections ↗Checked 2026-11-05
• Composio fetching tools and schemas ↗Checked 2026-11-05
• Composio execute tool API ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.