# Troubleshooting

Source: https://docs.graphops.xyz/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](https://platform.graphops.xyz/organizations/current/overview?support=open)
with the details listed under [Contact support](#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`](/platform/errors/api-keys#api_key_class_not_allowed).
6. Remove extra quotes, whitespace, or the literal string `Bearer` from secret-manager values.
7. Use [Authentication](./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](/platform/billing-and-credits#automatic-top-ups).
2. `api_key_route_not_allowed`: confirm the endpoint uses `deploymentCID`, `subgraphId` or `alias`
as shown in [Authentication](./authentication).
3. `api_key_target_not_allowed`: the key's Subgraphs access is
[limited](/platform/api-keys#limit-a-key) 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](/platform/api-keys#use-a-key-in-a-browser). 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](https://platform.graphops.xyz/organizations/current/overview?support=open),
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](./guides/import-existing-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](./choose-a-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](https://platform.graphops.xyz/organizations/current/services/subgraphs/aliases) 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](./guides/import-existing-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](./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](https://platform.graphops.xyz/organizations/current/overview?support=open) 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](https://platform.graphops.xyz/organizations/current/overview?support=open).

## 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](./networks#managed-indexing) 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](./guides/deploy-with-graph-cli#publish-on-the-graph-network-optional) 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](./managed-subgraphs#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](https://platform.graphops.xyz/organizations/current/overview?support=open), 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

* [Monitor sync health](./guides/monitor-sync-health): Catch lag and indexing errors before users do.
* [Authentication](./authentication): Compare header and route-token formats.
* [Usage and limits](./usage-and-limits): Check rate limits, retries, and how queries are charged.