Subgraphs: Troubleshooting

Find the error or symptom you see, then work through its checks in order. If the issue remains after the checks, contact GraphOps support with the details listed under Contact support.

`401 Unauthorized`

The request is missing a valid API key, the Authorization header is malformed, or the route-token URL does not include a valid key.

Confirm the key was created for the organization that owns Subgraphs access.
For header auth, confirm the header is exactly Authorization: Bearer <GRAPHOPS_API_KEY>.
For route-token auth, confirm the endpoint ends with /<GRAPHOPS_API_KEY>.
Confirm the key has not been revoked or rotated.
Remove extra quotes, whitespace, or the literal string Bearer from secret-manager values.
Use Authentication to compare header and route-token formats.

`403 Forbidden`

The key is valid, but the organization is not entitled to the endpoint, Endpoint Alias, Subgraph, or feature.

Confirm the organization has Subgraphs enabled.
Confirm the API key belongs to the same organization that owns the Endpoint Alias or Managed Subgraph.
Check your credit balance and whether service access is paused in Billing.

`404 Not Found`

The Deployment CID, Graph Network Subgraph ID, or Endpoint Alias does not resolve for the organization.

Confirm the endpoint mode: deploymentCID, subgraphId, or alias.
Confirm the identifier value in the platform UI.
For Endpoint Aliases, confirm the Endpoint Alias name is correct.
For Deployment CIDs, confirm the CID identifies a deployed Subgraph.
For Graph Network Subgraph IDs, confirm the Subgraph exists on The Graph Network.

Subgraph unavailable: no indexer is serving the deployment

The deployment has no active indexer allocations on The Graph Network. Its publication or presence in the discovery catalog does not guarantee that an indexer can serve queries. The explorer reports this as Subgraph unavailable; a direct query can return subgraph not found: no allocations inside a GraphQL errors array even with HTTP status 200.

Confirm the Deployment CID you want to query, including the current version if you use a Graph Network Subgraph ID or an Endpoint Alias that follows one.
An Owner or Developer can import it as a Managed Subgraph to start GraphOps managed indexing if its network is supported. If you have another role, ask an Owner or Developer to do this, or choose another deployment with available indexing.
Once indexing is ready, choose Retry in the explorer. Repeated requests alone do not create indexer coverage.

GraphQL validation errors

The query references a field, filter, ordering value, or entity type that does not exist in the Subgraph schema. The response has an errors array, often with HTTP status 200.

Run schema introspection or inspect the schema published with the Subgraph.
Confirm entity names and field casing.
Confirm generated filters such as id_gt or createdAtTimestamp_gte exist for that entity.
Confirm an Endpoint Alias update did not move the endpoint to a schema-incompatible deployment.
Use Schema reference for schema discovery guidance.

Historical block query fails

GraphOps Subgraphs are pruned, so queries with a historical block argument are not supported as a production feature.

Remove historical block query constraints.
Query the current indexed view.
Use _meta.block.number and _meta.block.hash to understand freshness.
Use a historical data workflow if the application needs block-by-block replay.

Empty or stale results

The Subgraph may not have indexed the expected block yet, the query may be too restrictive, or the application may be querying a different deployment than expected.

Query _meta.block.number and _meta.deployment.
Confirm the endpoint mode and identifier.
Confirm filters and ordering fields match the schema.
If using an Endpoint Alias, compare _meta.deployment with its resolved target. A Deployment CID target stays on that deployment. A Managed Subgraph target follows its serving Current version. A Graph Network Subgraph ID target follows its latest validated publication and can move before Managed Subgraph indexing is ready.
Compare _meta.block.number with your expected chain head only when you have a reliable head source for the same network.

`_meta.hasIndexingErrors` is `true`

The deployment serving the query reports indexing errors, so some entities may be missing or stale.

Log _meta.deployment, _meta.block.number, and _meta.block.hash.
Confirm whether the errors started after a Subgraph deployment or Endpoint Alias update.
Test a previous Deployment CID if you keep release records.
Contact GraphOps support with the endpoint and _meta values.

`429 Too Many Requests`

The organization exceeded a query-rate or concurrency limit.

Reduce parallel requests.
Add exponential backoff with jitter.
Page large scans with stable cursors.
Avoid running schema introspection on a hot path.
Request a plan or limit change through GraphOps support.

Managed Subgraph validation or status is unavailable

The deployment may use a network that managed indexing does not support, or the latest status could not be received.

Validate the immutable Deployment CID in the platform UI.
Confirm that the deployment uses one supported network across all data sources and templates.
On the detail page, check the status label, indexing progress, and Status updated time. The timestamp shows when the status was last received; it does not mean indexing has caught up with the network.
If a status or measurement shows Unavailable, refresh the detail page before starting, promoting, or removing the resource. Contact support if the information remains unavailable or you cannot complete the action.

Contact support

When contacting GraphOps support, include:

Organization name or ID.
Endpoint mode: Deployment CID, Graph Network Subgraph ID, or Endpoint Alias.
Identifier value, with API keys redacted.
Approximate timestamp.
HTTP status or GraphQL error message.
_meta.deployment, _meta.block.number, and _meta.block.hash when available.
Whether the request used header auth or route-token auth.