Skip to content

Troubleshooting

Diagnose common Subgraphs authentication, identifier, schema, sync, and limit issues.

Find the error or symptom you see, then work through its checks in order. If the issue remains after the checks, contact GraphOps support(opens in a new tab) 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.

  1. Confirm the key was created for the organization that owns Subgraphs access and includes Subgraphs.
  2. For header auth, confirm the header is exactly Authorization: Bearer <GRAPHOPS_API_KEY>.
  3. For route-token auth, confirm the endpoint ends with /<GRAPHOPS_API_KEY>.
  4. Confirm the key has not been revoked or rotated.
  5. Confirm you send a query key, which starts with gqk_. Subgraphs refuses a service account API key (gsk_) with the code api_key_class_not_allowed.
  6. Remove extra quotes, whitespace, or the literal string Bearer from secret-manager values.
  7. Use Authentication to compare header and route-token formats.

403 Forbidden

The key is valid, but GraphOps refuses the request. The response code names the reason.

  1. credits_exhausted: the organization has no credits left. Add credits in Billing to bring the balance above zero. Access is restored automatically. To avoid a repeat, turn on automatic top-ups.
  2. api_key_route_not_allowed: confirm the endpoint uses deploymentCID, subgraphId or alias as shown in Authentication.
  3. api_key_target_not_allowed: the key's Subgraphs access is limited and no limit matches the identifier in your endpoint. A Deployment CID limit does not allow an Endpoint Alias that serves the same deployment, and a Managed Subgraph limit stops allowing a previous version's Deployment CID after a promotion.
  4. api_key_origin_not_allowed or api_key_origin_required: the key limits Subgraphs to allowed origins. For a browser request, confirm one matches the page's origin exactly, including its scheme and port, such as http://localhost:3000. A server, script, or curl request sends no origin, so use a key whose Subgraphs access has no allowed origins there instead.
  5. Confirm the API key belongs to the same organization that owns the Endpoint Alias or Managed Subgraph.
  6. usage_access_paused, organization_disabled or api_key_disabled: GraphOps support paused the organization or disabled the key. Adding credits does not restore access. Contact GraphOps support(opens in a new tab), or create a new key if only the key is disabled.

404 Not Found

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

  1. Confirm the endpoint mode: deploymentCID, subgraphId, or alias.
  2. Confirm the identifier value in the platform UI.
  3. For Endpoint Aliases, confirm the Endpoint Alias name is correct.
  4. For Deployment CIDs, confirm the CID identifies a deployed Subgraph.
  5. 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.

  1. 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.
  2. 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.
  3. Once indexing is ready, choose Retry in the explorer. Repeated requests alone do not create indexer coverage.

Subgraph unavailable: indexers report an indexing error

Every indexer serving the deployment has stopped on an indexing error, so The Graph Network does not answer queries for it. The explorer reports this as Subgraph unavailable and can still show the deployment's metadata. A direct query can return bad indexers: {…: BadResponse(no attestation: indexing_error)} inside a GraphQL errors array.

  1. Check the Subgraph's current version. A publisher usually fixes an indexing error by publishing a new deployment, and a Graph Network Subgraph ID or an Endpoint Alias that follows one moves to it.
  2. Otherwise choose another deployment, or ask the publisher to fix the Subgraph and redeploy it. Retrying the same deployment does not clear the error.

Queries fail or return less data after a new version is published

Your endpoint moved to a new version that is not fully indexed yet. A subgraphId endpoint, or an Endpoint Alias with a Graph Network Subgraph ID target and the Latest published version target behavior, moves as soon as the owner publishes a version. Until the new version catches up, queries can report that no indexer is serving the deployment, return fewer entities or an older _meta.block.number, or fail validation against a changed schema.

  1. Query _meta.deployment and compare it with the Deployment CID you tested against.
  2. To keep serving the previous version now, query its deploymentCID endpoint, or change your Endpoint Alias to a Deployment CID target for that CID. This works while an indexer still serves the previous version.
  3. To avoid the gap in future, point your application at an Endpoint Alias with the Latest available version target behavior, which waits for indexers to serve each new version, or at one that targets a Managed Subgraph that follows the Subgraph. See Choose your Subgraph setup.

Endpoint Alias hasn't moved to the latest version

An Endpoint Alias with a Graph Network Subgraph ID target and the Latest available version target behavior keeps serving the previous version until an indexer on The Graph Network reports the latest one healthy and close to the chain head.

  1. Open Endpoint Aliases(opens in a new tab) and find the Endpoint Alias. The Target column shows the Latest Deployment CID and why it isn't serving yet.
  2. Wait for indexers to catch up on the new version. The Endpoint Alias moves on its own once they do.
  3. To serve the latest version now, change the target behavior to Latest published version, or change the target to its Deployment CID. Queries can fail or return incomplete data until indexers catch up.
  4. If no indexer serves the new version for a long time, an Owner or Developer can import it as a Managed Subgraph to index it with GraphOps.

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.

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

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.

  1. Query _meta.block.number and _meta.deployment, or read the X-Deployment-CID response header.
  2. Confirm the endpoint mode and identifier.
  3. Confirm filters and ordering fields match the schema.
  4. If using an Endpoint Alias, compare X-Deployment-CID or _meta.deployment with the serving Deployment CID shown for it in the platform UI. A Deployment CID target stays on that deployment. A Managed Subgraph target serves its Current version, or its Next version, which can be partially indexed, with the Next version behavior. A Graph Network Subgraph ID target with Latest published version can move before indexers serve the new version.
  5. 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.

  1. Log _meta.deployment, _meta.block.number, and _meta.block.hash.
  2. Confirm whether the errors started after a Subgraph deployment or Endpoint Alias update.
  3. Test a previous Deployment CID if you keep release records.
  4. Contact GraphOps support(opens in a new tab) with the endpoint and _meta values.

429 Too Many Requests

The organization exceeded a query-rate or concurrency limit.

  1. Reduce parallel requests.
  2. Add exponential backoff with jitter.
  3. Page large scans with stable cursors.
  4. Avoid running schema introspection on a hot path.
  5. Request a limit increase through GraphOps support(opens in a new tab).

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.

  1. Validate the immutable Deployment CID in the platform UI.
  2. Confirm that the deployment uses one managed indexing network across all data sources and templates.
  3. On the detail page, hover over, focus, or tap the status label for its explanation. Check 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.
  4. 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.

A Managed Subgraph can't follow a Graph Network Subgraph ID

Change target type keeps the Graph Network Subgraph ID choice disabled, or the ID you entered shows an error.

  1. If a Next version is staged, promote it or cancel the upgrade first.
  2. Check that the ID's current version uses the same network as the Managed Subgraph.
  3. Check that the currently indexing deployment is one of the versions published to the ID. If it isn't, publish it to the ID first.
  4. To follow a different ID than the one it follows now, change the target type to a Deployment CID first.

See Change the target type for every requirement.

Managed indexing has stopped

Open the explanation on the affected version's status label. If it identifies an error in your Subgraph, use the affected block and source location, when provided, to inspect the mapping, schema, entity data, ABI or manifest. Deploy a corrected version after resolving the cause.

If the explanation asks you to contact support, include the Deployment CID, the affected block and the Status updated time. Check Current and Next separately: a failed upgrade can leave the serving version healthy.

Contact support

When contacting GraphOps support(opens in a new tab), 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.
  • The X-Deployment-CID response header, and _meta.deployment, _meta.block.number, and _meta.block.hash when available.
  • Whether the request used header auth or route-token auth.

Next steps

Last updated

Usage and limits

Understand Subgraphs query metering, Managed Subgraphs, rate limits, and production safeguards.