Skip to main content
Graphman is a powerful command-line tool included with Graph Node for managing subgraph deployments, performing maintenance operations, and troubleshooting issues.

​
Getting Started

Graphman is included in the official Graph Node containers. You can access it by running: 
docker exec -it <graph-node-container> graphman --config config.toml <command>
Graphman requires a configuration file to connect to your Graph Node infrastructure. If you don’t have one, follow the basic setup instructions to create a minimal configuration.

​
Environment Variables

Graphman respects the GRAPH_LOG environment variable for logging output. To disable logs: 
unset GRAPH_LOG
graphman --config config.toml <command>

​
Verifying Setup

Test that graphman is configured correctly: 
graphman --config config.toml info some/subgraph
If successful, this will display basic information about the deployment, including its database namespace.

​
Core Commands

​
Info

Prints detailed information about a deployment. Synopsis: 
graphman --config <CONFIG> info [OPTIONS] <DEPLOYMENT>
Arguments:
  • <DEPLOYMENT> - The deployment identifier (subgraph name, IPFS hash Qm.., or database namespace sgdNNN)
Options:
  • -c, --current - List only current version
  • -p, --pending - List only pending versions
  • -u, --used - List only used (current and pending) versions
  • -s, --status - Include status information
Output Fields: By default, the info command displays:
  • name - The subgraph name
  • status - Either pending or current
  • id - The Qm... IPFS identifier
  • namespace - Database schema containing deployment tables
  • shard - Database shard location
  • active - Whether this version is used for queries
  • chain - The blockchain network
  • graph node id - The assigned node instance
With --status enabled, additional fields include:
  • synced - Whether synced to current chain head
  • health - healthy, unhealthy, or failed
  • latest indexed block - Most recent processed block
  • current chain head block - Latest blockchain block
Examples: 
graphman --config config.toml info subgraph-name

graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66 --status

​
Remove

Removes the association between a subgraph name and its deployment. Synopsis: 
graphman --config <CONFIG> remove <NAME>
Arguments:
  • <NAME> - The name of the subgraph to remove
This command does not delete indexed data. It only removes the name mapping, stopping query traffic to that name and freeing it for reuse.
Example: 
graphman --config config.toml remove subgraph-name

​
Unassign

Stops Graph Node from indexing a deployment permanently. Synopsis: 
graphman --config <CONFIG> unassign <DEPLOYMENT>
Arguments:
  • <DEPLOYMENT> - The deployment identifier
No indexed data is lost. The deployment remains in the database but stops receiving updates. See Maintenance Operations for more details on assignment management.
Examples: 
graphman --config config.toml unassign subgraph-name

graphman --config config.toml unassign QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

​
Drop

Completely deletes a deployment and all its indexed data. Synopsis: 
graphman --config <CONFIG> drop [OPTIONS] <DEPLOYMENT>
Arguments:
  • <DEPLOYMENT> - The deployment identifier
Options:
  • -c, --current - Search only for current versions
  • -p, --pending - Search only for pending versions
  • -u, --used - Search only for used versions
  • -f, --force - Skip confirmation prompt
This operation is irreversible. The drop command executes these steps in sequence:
1

Query deployment info

Runs graphman info <deployment> to identify the deployment
2

Unassign deployment

Runs graphman unassign <deployment> to stop indexing
3

Remove name mapping

Runs graphman remove <name> to free the subgraph name
4

Mark as unused

Runs graphman unused record to register for deletion
5

Delete data

Runs graphman unused remove <deployment> to purge all data
Examples: 
graphman --config config.toml drop QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

graphman --config config.toml drop author/subgraph-name

​
Cleanup Commands

​
Unused Record

Scans all shards for unused deployments and registers them for removal. Synopsis: 
graphman unused record
Description: Identifies deployments that meet all these criteria:
  1. Not assigned to any node
  2. Either not marked as active, or neither current nor pending version of a subgraph
  3. Not the source of a currently running copy operation
Recorded deployments are stored in the unused_deployments table in the primary shard.
This command does not delete any data. It only marks deployments for future removal.
Example: 
graphman --config config.toml unused record

​
Unused Remove

Deletes deployments previously marked as unused. Synopsis: 
graphman unused remove [OPTIONS]
Options:
  • -c, --count <COUNT> - How many unused deployments to remove (default: all)
  • -d, --deployment <DEPLOYMENT> - Remove a specific deployment
  • -o, --older <OLDER> - Remove only deployments recorded at least this many minutes ago
This operation is irreversible. All indexed data for removed deployments is permanently deleted.
Deployments are removed in descending order by entity count (smaller deployments first). Examples: 
graphman --config config.toml unused remove

graphman --config config.toml unused remove --older 720

graphman --config config.toml unused remove --deployment QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

​
Chain Management

​
Check Blocks

Validates cached blocks against fresh data from the JSON RPC provider. Synopsis: 
graphman --config <config> chain check-blocks <chain-name> <SUBCOMMAND>
Arguments:
  • <chain-name> - Chain name (must be configured in your config file)
Subcommands:
  • by-hash <hash> - Check a single block by hash
  • by-number <number> - Check a single block by number
  • by-range [--from <n>] [--to <n>] - Check a range of blocks
Options for by-number and by-range:
  • --delete-duplicates - Automatically remove duplicate blocks at the same height
Description: JSON RPC providers sometimes send invalid block data to Graph Node. This command compares cached blocks with fresh data from the provider and removes any mismatches. When multiple blocks exist for the same block number, graphman will abort unless --delete-duplicates is specified, which removes all duplicates for that block number. Examples: 
graphman --config config.toml chain check-blocks mainnet by-hash 0xd56a9f64c7e696cfeb337791a7f4a9e81841aaf4fcad69f9bf2b2e50ad72b972

graphman --config config.toml chain check-blocks mainnet by-number 15626962

graphman --config config.toml chain check-blocks mainnet by-range --from 15626900 --to 15626962 --delete-duplicates

graphman --config config.toml chain check-blocks mainnet by-range --from 13000000

​
Call Cache Remove

Removes call cache entries for a specified chain. Synopsis: 
graphman chain call-cache <CHAIN_NAME> remove [OPTIONS]
Options:
  • --from <FROM> - Starting block number
  • --to <TO> - Ending block number
  • --remove-entire-cache - Remove the complete cache
  • --ttl-days <TTL_DAYS> - Remove contracts not accessed for this many days
  • --ttl-max-contracts <MAX> - Limit number of contracts removed with TTL
Removing the entire cache can significantly reduce indexing performance and should generally be avoided.
Block Range Options: When using --from and --to:
  • Omitting --from starts from the first cached block
  • Omitting --to extends to the last cached block
TTL-Based Removal: The --ttl-days option removes stale contracts based on the call_meta.accessed_at field. For example, --ttl-days 7 removes all calls to contracts not accessed in the last 7 days. Use --ttl-max-contracts to limit how many contracts are removed in a single operation. Examples: 
graphman --config config.toml chain call-cache ethereum remove --from 10 --to 20

graphman --config config.toml chain call-cache ethereum remove --remove-entire-cache

graphman --config config.toml chain call-cache ethereum remove --ttl-days 7

graphman --config config.toml chain call-cache ethereum remove --ttl-days 7 --ttl-max-contracts 100

​
Workflow Examples

​
Typical Cleanup Workflow

When you need to free up disk space by removing old deployments:
1

Identify unused deployments

graphman --config config.toml unused record
This scans all shards and marks unused deployments.
2

Review what will be removed

graphman --config config.toml unused list -e
Inspect the list of deployments marked for removal.
3

Remove unused deployments

graphman --config config.toml unused remove
Permanently delete the indexed data for unused deployments.

​
Migrating a Deployment

To stop serving a subgraph and free its name for a new version:
1

Remove the name mapping

graphman --config config.toml remove author/subgraph-name
This stops query traffic to the old version.
2

Record as unused

graphman --config config.toml unused record
Mark the old deployment for cleanup.
3

Deploy new version

Deploy your new subgraph version. It can now use the freed name.
4

Clean up old data

graphman --config config.toml unused remove
Remove the old deployment data after confirming the new version works.

​
Best Practices

Before running destructive commands like drop or unused remove, use info and unused list to verify which deployments will be affected.
The --force flag skips confirmation prompts. Only use it in automated scripts after thorough testing.
Use --older with unused remove to ensure deployments have been unused for a safe period (e.g., 24 hours) before deletion.
Regularly run check-blocks on critical block ranges to ensure data integrity, especially after RPC provider changes.
Use TTL-based removal instead of clearing the entire cache to maintain indexing performance.

​
Troubleshooting

​
Graphman can’t connect to database

Ensure your config file has correct database connection strings and that the database is accessible from the container.

​
Deployment not found

Verify the deployment identifier using: 
graphman --config config.toml info <deployment>
Try different identifier formats (name, IPFS hash, namespace).

​
Check-blocks finds mismatches

This indicates your RPC provider sent incorrect data. The command automatically removes bad cached blocks. Consider switching to a more reliable RPC provider.

​
Unused remove doesn’t delete a deployment

Ensure the deployment was marked as unused with graphman unused record first. Check that it’s not currently assigned to a node.

Build docs developers (and LLMs) love

Get started for freeTalk to us