Docs
Search⌘ K
  • Home
  • About The Graph
  • Supported Networks
  • Protocol Contracts
  • AI Tooling
  • Subgraphs
    • Substreams
      • Indexer Software
        • Gateway Software
          • Data Services
            • Resources
              Subgraphs > Guides & Best Practices

              4 minutes

              Debug Faster with Subgraph Forking

              Syncing a Subgraph to the block where it failed can take hours, and every attempted fix means another wait. Subgraph forking, developed by LimeChain⁠, removes that wait: you reproduce and fix the failure locally without syncing to the failing block. This guide shows how to use it.

              What Subgraph Forking Is

              Subgraph forking is the process of lazily fetching entities from another Subgraph’s store (usually a remote one).

              In the context of debugging, Subgraph forking allows you to debug your failed Subgraph at block X without needing to wait to sync-up to block X.

              How It Works

              When you deploy a Subgraph to a remote Graph Node for indexing and it fails at block X, the good news is that the Graph Node will still serve GraphQL queries using its store, which is synced-up to block X. You can use this up-to-date store to fix the bug that occurs at block X.

              In short, you fork the failing Subgraph from a remote Graph Node that is guaranteed to have the Subgraph indexed up to block X in order to provide the locally deployed Subgraph being debugged at block X an up-to-date view of the indexing state.

              Example: Fix a Failing Gravatar Subgraph

              To stay focused on debugging, this example uses the example-Subgraph⁠ indexing the Ethereum Gravity smart contract.

              Here are the handlers that index Gravatars. They look correct:

              1export function handleNewGravatar(event: NewGravatar): void {2  let gravatar = new Gravatar(event.params.id.toHex().toString())3  gravatar.owner = event.params.owner4  gravatar.displayName = event.params.displayName5  gravatar.imageUrl = event.params.imageUrl6  gravatar.save()7}89export function handleUpdatedGravatar(event: UpdatedGravatar): void {10  let gravatar = Gravatar.load(event.params.id.toI32().toString())11  if (gravatar == null) {12    log.critical('Gravatar not found!', [])13    return14  }15  gravatar.owner = event.params.owner16  gravatar.displayName = event.params.displayName17  gravatar.imageUrl = event.params.imageUrl18  gravatar.save()19}

              When you deploy this Subgraph to Subgraph Studio, it fails with the “Gravatar not found!” error.

              The usual way to attempt a fix is:

              1. Make a change in the mappings that you believe will solve the issue.
              2. Re-deploy the Subgraph to Subgraph Studio (or another remote Graph Node).
              3. Wait for it to sync.
              4. If it breaks again, go back to step 1.

              Step 3 is what makes this slow. Subgraph forking removes it:

              1. Spin-up a local Graph Node with the appropriate fork-base set.
              2. Make a change in the mappings source, which you believe will solve the issue.
              3. Deploy to the local Graph Node, forking the failing Subgraph and starting from the problematic block.
              4. If it breaks again, go back to step 1.

              Two terms need explaining:

              • fork-base is the base URL of the remote store. When you append a Subgraph ID, the result (<fork-base>/<subgraph-id>) is a valid GraphQL endpoint for that Subgraph’s store.
              • Forking the failing Subgraph means passing its ID to graph deploy with --debug-fork:
              1$ graph deploy <subgraph-name> --debug-fork <subgraph-id> --ipfs http://localhost:5001 --node http://localhost:8020

              Also set dataSources.source.startBlock in the manifest to the problematic block, so the local node skips the blocks before it and reads that state from the fork.

              Here is the full fix for the Gravatar example:

              1. Start a local Graph Node (setup instructions⁠) with the fork-base option set to https://api.thegraph.com/subgraphs/id/, so that it can fork the failing Subgraph deployed to Subgraph Studio.
              1$ cargo run -p graph-node --release -- \2    --postgres-url postgresql://USERNAME[:PASSWORD]@localhost:5432/graph-node \3    --ethereum-rpc NETWORK_NAME:[CAPABILITIES]:URL \4    --ipfs 127.0.0.1:50015    --fork-base https://api.thegraph.com/subgraphs/id/
              1. Inspect the handlers. The two handlers use different id representations for Gravatars. While handleNewGravatar converts it to a hex (event.params.id.toHex()), handleUpdatedGravatar uses an int32 (event.params.id.toI32()) which causes the handleUpdatedGravatar to panic with “Gravatar not found!”. Change both handlers to convert the id to hex.
              2. Deploy the fixed Subgraph to the local Graph Node, forking the failing Subgraph and setting dataSources.source.startBlock to 6190343 in subgraph.yaml:
              1$ graph deploy gravity --debug-fork QmNp169tKvomnH3cPXTfGg4ZEhAHA6kEq5oy1XDqAxqHmW --ipfs http://localhost:5001 --node http://localhost:8020
              1. Check the local Graph Node logs to confirm that the handler now succeeds at the problematic block.
              2. Deploy the fixed Subgraph to Subgraph Studio or another remote Graph Node.

              Learn More

              • Graph Node Dev Mode: run and iterate on a Subgraph locally.
              • Grafting: ship the fix without a full re-index.
              • Guides & Best Practices overview: the full checklist and how this page fits with the rest of the section.
              ⁠Edit on GitHub⁠

              Secure API Keys with Next.jsGrafting
              On this page
              • What Subgraph Forking Is
              • How It Works
              • Example: Fix a Failing Gravatar Subgraph
              • Learn More
              The GraphStatusTestnetBrand AssetsForumSecurityPrivacy PolicyTerms of Service