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 markedidentity_onlybyfind_security, and most tools answernot_coveredfor 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 bareBTCis 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'spermission_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.