Guides›Composio Troubleshooting

Composio Troubleshooting

When Composio tools fail, check both account-link state and runtime execution reports.

Where to look first

1) Linked account state

Use V1 API:

GET /v1/agents/:id/composio/linked-accounts

or inspect DB table:

project_agent_provider_accounts

Key columns:

provider
principal_type / principal_id
status
external_account_ref
last_validated_at

2) Runtime execution reports

Inspect table:

runtime_composio_execution_reports

This is the fastest source for provider/tool failures by agent.

Useful SQL snippets

sql

-- Latest Composio failures for one agent
select
  created_at,
  provider,
  tool,
  status,
  error_code,
  error_message,
  metadata
from runtime_composio_execution_reports
where agent_id = '<agent_id>'
  and status = 'failed'
order by created_at desc
limit 100;

sql

-- Linked-account status by principal
select
  provider,
  principal_type,
  principal_id,
  status,
  external_account_ref,
  last_validated_at,
  updated_at
from project_agent_provider_accounts
where agent_id = '<agent_id>'
order by provider, principal_type, principal_id;

Common error patterns

Symptom / Code	Meaning	Action
`SETUP_INCOMPLETE`	Provider not enabled, missing auth config, or missing Composio key	Save project `composio` key and enable provider
`INVALID_CREDENTIALS`	Stored Composio key is invalid	Rotate project Composio key
`COMPOSIO_LINK_REQUIRED`	Principal has no active linked account	Run linked-account initiate flow for that principal
`COMPOSIO_LINK_REAUTH_REQUIRED`	Linked account revoked/expired/error	Re-link account for same provider/principal
`COMPOSIO_LINK_RESOLVE_FAILED`	Runtime could not resolve linked account	Check runtime health and core runtime endpoint availability
`COMPOSIO_AUTH_EXPIRED` / `COMPOSIO_AUTH_REVOKED`	Provider token no longer valid	Reconnect provider account
`COMPOSIO_TIMEOUT`	Upstream Composio/provider timeout	Retry once, then inspect provider/composio status

Status interpretation

Linked status	Meaning	Next step
`pending`	Link initiated but not completed	Finish OAuth callback flow
`active`	Ready for execution	No action
`revoked` / `expired` / `error`	Account unusable	Re-link
missing row	Never linked for that principal	Initiate new link

Principal mismatch check

If linking looks correct but tools still fail:

Confirm the message used the expected executionPrincipal.
Confirm linked account exists for the same provider + principal_type + principal_id.
Confirm agent default principal is what you expect when request-level override is omitted.

Telemetry signals

You may also see these events in app logs:

composio_token_missing_or_inactive
composio_token_expired
composio_credentials_revoked
composio_provider_not_configured
composio_upstream_error