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:
- Make a change in the mappings that you believe will solve the issue.
- Re-deploy the Subgraph to Subgraph Studio (or another remote Graph Node).
- Wait for it to sync.
- If it breaks again, go back to step 1.
Step 3 is what makes this slow. Subgraph forking removes it:
- Spin-up a local Graph Node with the appropriate fork-base set.
- Make a change in the mappings source, which you believe will solve the issue.
- Deploy to the local Graph Node, forking the failing Subgraph and starting from the problematic block.
- If it breaks again, go back to step 1.
Two terms need explaining:
fork-baseis 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 deploywith--debug-fork:
1$ graph deploy <subgraph-name> --debug-fork <subgraph-id> --ipfs http://localhost:5001 --node http://localhost:8020Also 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:
- Start a local Graph Node (setup instructions) with the
fork-baseoption set tohttps://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/- Inspect the handlers. The two handlers use different
idrepresentations forGravatars. WhilehandleNewGravatarconverts it to a hex (event.params.id.toHex()),handleUpdatedGravataruses an int32 (event.params.id.toI32()) which causes thehandleUpdatedGravatarto panic with “Gravatar not found!”. Change both handlers to convert theidto hex. - Deploy the fixed Subgraph to the local Graph Node, forking the failing Subgraph and setting
dataSources.source.startBlockto6190343insubgraph.yaml:
1$ graph deploy gravity --debug-fork QmNp169tKvomnH3cPXTfGg4ZEhAHA6kEq5oy1XDqAxqHmW --ipfs http://localhost:5001 --node http://localhost:8020- Check the local Graph Node logs to confirm that the handler now succeeds at the problematic block.
- 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.