Skip to content

Troubleshooting

Start with your situation below. Problems with the command-line client, REST or the registry tools follow under Registry tools, CLI and REST.

Connecting an AI app

The app is refused at sign-in

Argus accepts sign-in only from registered apps. Claude is registered; other hosted apps, such as ChatGPT, Claude Code, Cursor or Gemini CLI, are refused until Argus registers them, and no setting on your side changes that. Write to [email protected] and name the app. See supported AI apps.

"Invalid scope" at sign-in

The app asked for permissions Argus does not offer. Remove the connector and add it again with the address https://mcp.argusfa.com/mcp exactly, without a path or query of your own. A token with fewer scopes still connects and is offered fewer tools.

A tool answers needs_permission

The tool needs Memory or Holdings, and you have not allowed it for this app, or the sign-in must be renewed. The answer's error.fix links to the app's switches in the web app; see your account. After you change a switch, ask again.

A tool answers temporarily_unavailable with retry_after_s

For a company outside the list captured ahead of time, the first question starts a capture of its filings, events and end-of-day prices. It takes about a minute; retry_after_s says when to ask again. The same status also means that a source is briefly unavailable.

not_covered, not_found and identity_only

  • not_covered: Argus has no data of this kind for the subject. It never means the security does not exist. A security Argus can only name is marked identity_only by find_security, and most tools answer not_covered for it.
  • not_found: the SEC ticker lists Argus holds are complete and current and do not name the ticker, or a private item does not exist.
  • A crypto asset is written as a pair, such as BTC-USD; a bare BTC is read as a listed security's ticker.

See consumer-result-v1 for every code.

quota_exceeded

A usage limit was reached, the day's limit of first captures was reached, or too many requests from your account are running at once. The message says which. Wait and ask again; do not open more connections to get around it.

HTTP 451 region_unavailable

Argus is not offered in your region. The answer is HTTP 451 with the code region_unavailable. See eligibility.

Registry tools, CLI and REST

Start with the HTTP status or CLI exit code, then inspect audit_id. Legacy financial envelopes use error.error_code; personal tool results use problem.code and payload. Consumer tools on /mcp return consumer-result-v1: read status, error.code and notes; audit ids are in the MCP result's _meta.argus. See consumer-result-v1. Authentication or schema errors can precede any envelope. Avoid changing multiple credentials, scopes, settings, and request fields at once.

Edge rejection (403, Cloudflare 1010)

A plain error code: 1010 response comes from Cloudflare before the request reaches Argus. Production checks accept the Argus CLI, standard HTTPX and curl, but Cloudflare rejects Python urllib's default User-Agent. Custom clients should send an identifying header such as User-Agent: ArgusAgent/1.0. Keep the normal OAuth or machine credential headers; a User-Agent does not authenticate a request. An Argus authorization error instead has a structured error_code and audit_id.

Authentication (401)

For personal access, run argus auth status and confirm that the registered session matches the interface: API and MCP use separate audiences. Public MCP requires OAuth. A machine API key is supported only on the designated machine paths and cannot authorize private personal operations.

Error code Check
missing_credential Supply the supported Bearer session/token, or a machine credential on an endpoint that accepts it
invalid_credential No whitespace/truncation; correct environment and service
expired_credential / revoked_credential Sign in again; use the operator workflow for machine credentials
institution_mismatch For machine requests, check the credential's institution mapping; omit institution_id with OAuth
caller_mismatch For machine requests, check the credential's caller mapping; omit caller_id with OAuth
tool_not_allowed Credential tool allowlist includes the registry tool id
rate_limit_exceeded Back off until the credential window resets; do not rotate to evade limits

Governance denial (400 or 403)

Current deployments do not block otherwise permitted facts because of investment intent. Confirm the server registry version and policy configuration.

  • permission_denied: compare credential scopes with the registry's permission_requirements.required_scopes.
  • tenant_isolation_denied: remove cross-institution object references.
  • license_denied: check the source rights for your purpose, fields and redistribution settings. Use a permitted source or obtain the required rights; do not disable enforcement.
  • output_policy_denied: Argus-originated advice or an invalid output category was rejected. Verbatim, labeled source material remains eligible for fact output.

An unchanged retry will normally produce the same denial and a new audit record.

Request validation (422)

Fetch /openapi.json and compare the exact path schema. Common causes are naive timestamps without timezone, wrong camel/snake casing, unknown fields, an invalid US market session, reversed time ranges, empty required arrays, or a string where an array is required.

Personal invalid_input can also come from business validation after the outer JSON schema passes. For saved queries, check the selected tool's normalized parameters (company_id for company_fact_snapshot, not ticker). For confirmation preparation, validate the nested target request, including its own request_id where required. A filing workflow's payload.data.status may be clarification_required with no transport or problem error: supply the exact basis, period and filing version in clarifications before expecting a fact. See personal examples.

Empty or incomplete result

Check known_time <= as_of, requested company/ticker identity, data period, evidence gap classification, source ingestion state, connector run status, license-restricted fields, and data_quality.issues. Use data_freshness_manifest, evidence_gap_report, and field_catalog before assuming the source has no data. These are diagnostics tools and need an explicit signed grant.

For persisted filings, use data_freshness_manifest with dataset: regulatory_filings (or filing_disclosure_facts), the actual filing source id (for example sec_edgar_filings), the canonical company id (for example cik:0000320193), and an available field such as revenue or filing.fragment. All four must match records in your institution. A market-data request must instead use the market datasets below. An unknown subject, different source, or absent field returns a typed empty result; it never substitutes another company's filings. The ingestion interval uses retrieval timestamps, while known_time retains the source publication time.

Persisted market freshness supports delayed_market_data and market_bars (bars), market_quote (quotes), market_trades (trades), and equity_market_data (all three observation kinds). Use the exact captured source_id and permanent security ID as subject, with a matching field such as close, delayed_market_data.close_price, or market_observation.value.bid_price. Unsupported datasets and unmatched source/subject/field/observation-kind combinations return empty; they do not relabel unrelated market captures. This measures persisted watermarks at the inspection time, not a provider connection or a future freshness guarantee. Quote, trade and intraday capture is disabled (ADR 0008), so end-of-day bars are the only market observations that receive new captures. Consumer connections see end-of-day bars only.

Connector validation failure

This is an operator check: the public edge answers 404 for connector routes. Run argus connector validate, then fix the first concrete issue: unsupported provider, disabled source, absent or placeholder provider secret, or an invalid local file path. When license enforcement is enabled, also check the assigned policy and allowed uses. A dry_run still requires valid authentication and provider access; license checks follow the server switches, as in a committed synchronization.

Service unready (503)

Read /health/ready and run the role-specific container health command. Typical causes are PostgreSQL connectivity or migration-head mismatch, Redis failure, object-storage access, missing Celery worker ping, stale Beat heartbeat, API loopback failure, or MCP initialization/tool-list failure.

CLI runs locally by mistake

Run argus auth status, then argus auth login if needed. A stored OAuth credential or ARGUS_ACCESS_TOKEN automatically selects https://api.argusfa.com. Machine clients can set that ARGUS_BASE_URL or pass --base-url. Do not use --local in a customer environment.

What to collect for escalation

Provide UTC timestamp, interface, tool id, HTTP status/CLI exit code, error_code, audit_id, task/run id if present, requested as_of, and the relevant readiness dependency. Redact API keys, authorization headers, provider secrets, full filing contents, and restricted fields.