Skip to main content
Graph Node behavior can be extensively configured through environment variables. This reference documents all available variables organized by category.
Some environment variable names may change in future releases. Always check the latest documentation when upgrading.

​
General Settings

​
GRAPH_NODE_ID
string
default:"default"
Unique identifier for this Graph Node instanceRequired when running multiple nodes in parallel. Each node must have a unique ID. The same node should use the same ID across restarts.
GRAPH_NODE_ID=index-node-1
​
GRAPH_NODE_ID_USE_LITERAL_VALUE
boolean
Use literal node_id value in Docker without replacing hyphens with underscoresDocker only. Changing this for an existing installation requires updating node_id values in subgraphs.subgraph_deployment_assignment table.
​
GRAPH_LOG
string
default:"info"
Graph Node logging configurationUses same syntax as Rust’s env_logger.
# Set global level
GRAPH_LOG=debug

# Module-specific levels
GRAPH_LOG=info,graph_store_postgres=debug

# Complex filtering
GRAPH_LOG=warn,graph_node::subgraph=info
Levels: error, warn, info, debug, trace
​
GRAPH_LOG_TIME_FORMAT
string
default:"%b %d %H:%M:%S%.3f"
Custom log timestamp formatUses chrono format syntax.
GRAPH_LOG_TIME_FORMAT="%Y-%m-%d %H:%M:%S"
​
GRAPH_LOG_QUERY_TIMING
string
Enable detailed query timing logsComma-separated list: sql, gql, cache
  • gql: Log GraphQL queries with timing, subgraph, variables, and unique query_id
  • sql: Log SQL queries with timing, bind variables, and entity counts
  • cache: Log cache hits/misses for GraphQL queries
GRAPH_LOG_QUERY_TIMING=gql,sql
​
GRAPH_LOG_POI_EVENTS
boolean
Log Proof of Indexing events deterministicallyUseful for debugging POI-related issues.
​
GRAPH_KILL_IF_UNRESPONSIVE
boolean
Kill the process if it becomes unresponsiveSet to any value to enable.
​
GRAPH_KILL_IF_UNRESPONSIVE_TIMEOUT_SECS
number
default:"10"
Timeout in seconds before killing unresponsive nodeOnly used if GRAPH_KILL_IF_UNRESPONSIVE is set.

​
Ethereum / EVM Chain Configuration

​
ETHEREUM_REORG_THRESHOLD
number
default:"250"
Maximum expected reorg size in blocksIf a larger reorg occurs, subgraphs may process inconsistent data.
ETHEREUM_REORG_THRESHOLD=500
​
ETHEREUM_POLLING_INTERVAL
number
default:"500"
How often to poll Ethereum for new blocks (milliseconds)
ETHEREUM_POLLING_INTERVAL=1000  # Poll every 1 second
​
GRAPH_ETHEREUM_TARGET_TRIGGERS_PER_BLOCK_RANGE
number
default:"100"
Target number of triggers to process per batchToo small: Excessive requests to Ethereum node Too large: Expensive calls and high memory usage
​
ETHEREUM_TRACE_STREAM_STEP_SIZE
number
default:"50"
Number of blocks to scan per RPC request when fetching tracesUsed for call handlers and block handlers with call filters.
​
ETHEREUM_BLOCK_BATCH_SIZE
number
default:"10"
Number of Ethereum blocks to request in parallelAlso limits parallel requests like trace_filter.
​
GRAPH_ETHEREUM_MAX_BLOCK_RANGE_SIZE
number
default:"1000"
Maximum block range to scan for triggers in each request
​
GRAPH_ETHEREUM_MAX_EVENT_ONLY_RANGE
number
default:"500"
Maximum range for eth_getLogs requests filtering only by event signature (not contract address)
​
GRAPH_ETHEREUM_JSON_RPC_TIMEOUT
duration
Timeout for Ethereum JSON-RPC requests
GRAPH_ETHEREUM_JSON_RPC_TIMEOUT=60s
​
GRAPH_ETHEREUM_REQUEST_RETRIES
number
default:"10"
Number of retries for Ethereum JSON-RPC requestsFor requests that won’t fail the subgraph but will restart syncing (e.g., requesting a reorged block).
​
GRAPH_ETHEREUM_BLOCK_INGESTOR_MAX_CONCURRENT_JSON_RPC_CALLS_FOR_TXN_RECEIPTS
number
default:"1000"
Maximum concurrent requests for transaction receipts during block ingestion
​
GRAPH_ETHEREUM_FETCH_TXN_RECEIPTS_IN_BATCHES
boolean
Fetch transaction receipts in batches instead of concurrentlyAutomatically set to true on macOS to avoid DNS issues.
​
GRAPH_ETHEREUM_CLEANUP_BLOCKS
boolean
Clean up unneeded blocks from the cacheDevelopment only. In production, causes multiple downloads of the same blocks. Cannot be used with multiple shards.
​
GRAPH_ETHEREUM_GENESIS_BLOCK_NUMBER
number
default:"0"
Specify genesis block number
​
GRAPH_ETH_GET_LOGS_MAX_CONTRACTS
number
default:"2000"
Maximum number of contracts to query in a single eth_getLogs request
​
GRAPH_ETHEREUM_BLOCK_RECEIPTS_CHECK_TIMEOUT
number
default:"10"
Timeout (seconds) for checking eth_getBlockReceipts supportIf timeout occurs, individual transaction receipts are fetched instead.
​
DISABLE_BLOCK_INGESTOR
boolean
Disable block ingestionSet to true to disable, false or unset to enable.
DISABLE_BLOCK_INGESTOR=true

​
Firehose Configuration

​
GRAPH_NODE_FIREHOSE_MAX_DECODE_SIZE
string
default:"25MB"
Maximum size of a message that can be decoded by Firehose
GRAPH_NODE_FIREHOSE_MAX_DECODE_SIZE=50MB

​
Mapping Handlers

​
GRAPH_MAPPING_HANDLER_TIMEOUT
number
Maximum execution time for a mapping handler (seconds)Default: unlimited
GRAPH_MAPPING_HANDLER_TIMEOUT=30
​
GRAPH_ENTITY_CACHE_SIZE
number
default:"10000"
Entity cache size in kilobytesDefault is 10MB.
GRAPH_ENTITY_CACHE_SIZE=50000  # 50MB
​
GRAPH_MAX_API_VERSION
string
default:"0.0.7"
Maximum supported apiVersion in subgraph manifestsSubgraphs with higher versions will be rejected.
​
GRAPH_MAX_SPEC_VERSION
string
default:"0.0.5"
Maximum supported specVersion in subgraph manifestsSubgraphs with higher versions will be rejected.
​
GRAPH_RUNTIME_MAX_STACK_SIZE
string
default:"512KiB"
Maximum WASM runtime stack sizeExecution stops with an error if exceeded.
GRAPH_RUNTIME_MAX_STACK_SIZE=1024KiB

​
IPFS Configuration

​
GRAPH_IPFS_TIMEOUT
number
default:"60"
Timeout for IPFS requests (seconds)Includes manifest files and ipfs.cat calls from mappings.
​
GRAPH_MAX_IPFS_FILE_BYTES
number
default:"26214400"
Maximum file size for ipfs.cat calls (bytes)Default: 25 MiBAffects both subgraph files and file data sources.
​
GRAPH_MAX_IPFS_MAP_FILE_SIZE
number
default:"268435456"
Maximum file size for ipfs.map (bytes)Default: 256 MBEntities from ipfs.map are kept in memory during processing.
​
GRAPH_MAX_IPFS_CACHE_SIZE
number
default:"50"
Maximum number of files to cache from IPFS
​
GRAPH_MAX_IPFS_CACHE_FILE_SIZE
number
default:"1048576"
Maximum size of each cached IPFS file (bytes)Default: 1 MiB
​
GRAPH_IPFS_REQUEST_LIMIT
number
default:"100"
Rate limit for IPFS file data source requests (per second)
​
GRAPH_IPFS_MAX_ATTEMPTS
number
default:"100000"
Maximum retry attempts for IPFS requestsPrevents infinite retries on file not found or other errors.
​
GRAPH_IPFS_CACHE_LOCATION
string
File or Redis cache location for IPFS filesExperimental. Can be:
  • redis://host:port - Redis cache
  • /path/to/directory - Filesystem cache (must be writable)
GRAPH_IPFS_CACHE_LOCATION=redis://localhost:6379
GRAPH_IPFS_CACHE_LOCATION=/var/cache/graph-node/ipfs
​
GRAPH_ALLOW_NON_DETERMINISTIC_IPFS
boolean
Enable ipfs.cat in subgraph mappingsExperimental and non-deterministic. Will be removed in future versions.

​
GraphQL Configuration

​
GRAPH_GRAPHQL_QUERY_TIMEOUT
number
Maximum GraphQL query execution time (seconds)Default: unlimited
GRAPH_GRAPHQL_QUERY_TIMEOUT=60
​
GRAPH_GRAPHQL_MAX_COMPLEXITY
number
Maximum GraphQL query complexityDefault: unlimitedIntrospection queries have complexity ~1 million. Set higher than that to allow introspection.
GRAPH_GRAPHQL_MAX_COMPLEXITY=10000000
​
GRAPH_GRAPHQL_MAX_DEPTH
number
default:"255"
Maximum GraphQL query depthMaximum allowed: 255
​
GRAPH_GRAPHQL_MAX_FIRST
number
default:"1000"
Maximum value for first argument in queries
GRAPH_GRAPHQL_MAX_FIRST=500
​
GRAPH_GRAPHQL_MAX_SKIP
number
Maximum value for skip argument in queriesDefault: unlimited
​
GRAPH_GRAPHQL_WARN_RESULT_SIZE
number
Log warning if GraphQL result exceeds this size (bytes)Default: unlimited
GRAPH_GRAPHQL_WARN_RESULT_SIZE=10000000  # 10MB
​
GRAPH_GRAPHQL_ERROR_RESULT_SIZE
number
Return error if GraphQL result exceeds this size (bytes)Default: unlimitedChecked during response construction to prevent excessive memory use.
​
GRAPH_GRAPHQL_HTTP_PORT
number
default:"8000"
Port for GraphQL HTTP server
​
GRAPH_SQL_STATEMENT_TIMEOUT
number
Maximum SQL query execution time during GraphQL execution (seconds)Default: unlimited
​
ENABLE_GRAPHQL_VALIDATIONS
boolean
default:"false"
Enable GraphQL specification validationsValidates queries follow GraphQL execution rules.
​
SILENT_GRAPHQL_VALIDATIONS
boolean
default:"true"
Only log GraphQL validation errors without failing queriesOnly used if ENABLE_GRAPHQL_VALIDATIONS=true.Queries may still fail during execution stage.
​
GRAPH_GRAPHQL_DISABLE_BOOL_FILTERS
boolean
Disable AND/OR filters for performanceUseful if complex filters cause performance issues.
​
GRAPH_GRAPHQL_DISABLE_CHILD_SORTING
boolean
Disable child-based sorting for performanceUseful if child sorting causes performance issues.
​
GRAPH_GRAPHQL_TRACE_TOKEN
string
Token to enable query tracingRequests with X-GraphTraceQuery header matching this token will include SQL query traces.
GRAPH_GRAPHQL_TRACE_TOKEN=secret-trace-token
Then in requests:
curl -H "X-GraphTraceQuery: secret-trace-token" http://localhost:8000/subgraphs/name/my-subgraph

​
GraphQL Query Caching

​
GRAPH_CACHED_SUBGRAPH_IDS
string
default:"*"
Subgraphs to cache queries for
  • *: Cache all subgraphs (default)
  • Comma-separated list: Cache specific subgraphs
GRAPH_CACHED_SUBGRAPH_IDS=QmSubgraph1,QmSubgraph2
​
GRAPH_QUERY_CACHE_BLOCKS
number
default:"1"
Number of recent blocks per network to keep in query cacheSet to 0 to disable caching. Keep small as lookup time and memory are proportional to this value.
​
GRAPH_QUERY_CACHE_MAX_MEM
number
default:"1000"
Maximum memory for query cache (MB)Default: 1 GBTotal cache memory is 2x this value (recent blocks + frequent queries).
​
GRAPH_QUERY_CACHE_STALE_PERIOD
number
default:"100"
Number of queries after which a cache entry can be considered stale
​
GRAPH_QUERY_CACHE_MAX_ENTRY_RATIO
number
default:"3"
Maximum cache entry size ratioResults larger than (cache shard size / ratio) won’t be cached.Set to 0 for no limit.

​
Database Configuration

​
STORE_CONNECTION_POOL_SIZE
number
default:"10"
Database connection pool sizeMay not be strictly adhered to due to implementation details.
​
GRAPH_STORE_CONNECTION_TIMEOUT
number
default:"5000"
Database connection timeout (milliseconds)If exceeded, database is assumed down.
​
GRAPH_STORE_SETUP_TIMEOUT
number
default:"30000"
Database setup operation timeout (milliseconds)Default: 30 secondsUsed for migrations and schema creation, which may take longer than normal operations.
​
GRAPH_STORE_CONNECTION_UNAVAILABLE_RETRY
number
default:"2"
Probe interval when database shard is unavailable (seconds)Only one request per interval attempts connection; others fail instantly.
​
THEGRAPH_STORE_POSTGRES_DIESEL_URL
string
PostgreSQL URL for running testsFormat: postgresql://user:password@host:port/database
THEGRAPH_STORE_POSTGRES_DIESEL_URL=postgresql://graph:graph@localhost:5432/graph-test
​
GRAPH_STORE_BATCH_TARGET_DURATION
number
default:"180"
Target duration for batch operations during copying/grafting (seconds)Controls transaction length for long-running operations.
​
GRAPH_STORE_BATCH_TIMEOUT
number
Maximum batch operation timeout (seconds)Default: unlimitedShould be a small multiple (e.g., 10x) of GRAPH_STORE_BATCH_TARGET_DURATION.If hit, batch size resets to 1 and retries.
​
GRAPH_STORE_BATCH_WORKERS
number
default:"1"
Number of parallel workers for batch operationsMinimum: 1Uses idle connections to copy tables in parallel during subgraph copy operations.
​
GRAPH_STORE_WRITE_BATCH_DURATION
number
default:"300"
How long to accumulate changes before writing (seconds)Set to 0 to disable write batching.
​
GRAPH_STORE_WRITE_BATCH_SIZE
number
default:"10000"
How many changes to accumulate before writing (kilobytes)Default: 10 MBSet to 0 to disable write batching.
​
GRAPH_STORE_DISABLE_CALL_CACHE
boolean
default:"false"
Disable storing/reading eth_call results from cacheUseful for indexers running their own RPC nodes. May significantly impact performance depending on eth_call execution time vs database lookup cost.
​
GRAPH_POSTPONE_ATTRIBUTE_INDEX_CREATION
boolean
Postpone creating attribute-based indexes during subgraph copyCan speed up syncing.
​
GRAPH_STORE_INSERT_EXTRA_COLS
number
default:"0"
Workaround for ‘too many parameters’ PostgreSQL errorsIf encountering “number of parameters must be between 0 and 65535” errors, set to ~10.Such errors are always Graph Node bugs; this provides a temporary workaround.

​
Database Pruning and History

​
GRAPH_STORE_HISTORY_SLACK_FACTOR
number
default:"1.2"
History accumulation threshold before pruningMinimum: 1.01At 1.2, subgraph is pruned when it contains 20% more history than its limit.
​
GRAPH_STORE_HISTORY_REBUILD_THRESHOLD
number
default:"0.5"
Prune by copying entities to new tables if removing more than this fractionMust be between 0 and 1, and greater than DELETE_THRESHOLD.
​
GRAPH_STORE_HISTORY_DELETE_THRESHOLD
number
default:"0.05"
Prune by deleting from existing tables if removing between this and REBUILD_THRESHOLDMust be between 0 and 1, and less than REBUILD_THRESHOLD.If removing less than this threshold, no pruning occurs.
​
GRAPH_MIN_HISTORY_BLOCKS
number
Minimum blocks to retain for subgraphs with historyBlocks: autoDefault: 2 × reorg threshold
​
GRAPH_REMOVE_UNUSED_INTERVAL
number
default:"360"
How long to wait before removing unused deployments (minutes)Default: 6 hoursGraph Node periodically marks unused deployments, then waits this interval before deletion.

​
Experimental Database Features

​
GRAPH_ENABLE_SQL_QUERIES
boolean
default:"false"
Enable experimental SQL query interface
​
GRAPH_STORE_ACCOUNT_LIKE_SCAN_INTERVAL_HOURS
number
Interval for account-like optimization scan (hours)Requires also setting:
  • GRAPH_STORE_ACCOUNT_LIKE_MIN_VERSIONS_COUNT
  • GRAPH_STORE_ACCOUNT_LIKE_MAX_UNIQUE_RATIO
Scans for tables that benefit from account-like optimization.Reads from info.table_stats materialized view (refreshes every 6 hours).
​
GRAPH_STORE_ACCOUNT_LIKE_MIN_VERSIONS_COUNT
number
Minimum total versions for account-like flaggingRequired for account-like optimization scan.
​
GRAPH_STORE_ACCOUNT_LIKE_MAX_UNIQUE_RATIO
number
Maximum unique entities to version ratioExample: 0.01 ≈ 1:100 entity-to-version ratioRequired for account-like optimization scan.

​
Load Management

​
GRAPH_LOAD_WINDOW_SIZE
number
default:"300"
Load measurement window size (seconds)Used with GRAPH_LOAD_BIN_SIZE for load throttling.
​
GRAPH_LOAD_BIN_SIZE
number
default:"1"
Load measurement bin size (seconds)Measurements within window are binned into intervals of this size.
​
GRAPH_LOAD_THRESHOLD
number
default:"0"
Database connection wait time threshold for throttling (milliseconds)Default: 0 (throttling disabled)If connection wait times exceed this, queries are throttled until wait times drop below threshold.
GRAPH_LOAD_THRESHOLD=100  # Throttle if waits exceed 100ms
​
GRAPH_LOAD_JAIL_THRESHOLD
number
Effort fraction threshold for permanently rejecting queriesWhen overloaded, queries causing more than this fraction of effort are permanently rejected (even after overload resolves).If unset, no queries are jailed (but still subject to throttling).
GRAPH_LOAD_JAIL_THRESHOLD=0.1  # Jail queries using >10% of effort
​
GRAPH_LOAD_SIMULATE
boolean
default:"false"
Simulate load management without declining queriesPerforms all load management steps but only logs decisions instead of rejecting queries.

​
Subgraph Features

​
EXPERIMENTAL_SUBGRAPH_VERSION_SWITCHING_MODE
string
default:"instant"
Subgraph version switching behavior
  • instant: Switch immediately when new version deployed
  • synced: Only switch after new deployment syncs (becomes “Pending” version)
​
GRAPH_START_BLOCK
string
Starting block for forked subgraphFormat: block_hash:block_number
GRAPH_START_BLOCK=0xabc123...:15000000
​
GRAPH_FORK_BASE
string
API URL for subgraph forking
GRAPH_FORK_BASE=https://api.thegraph.com/subgraphs/id/
​
GRAPH_DEBUG_FORK
string
IPFS hash of subgraph to fork
GRAPH_DEBUG_FORK=QmSubgraphHash

​
Example Configurations

​
Development Environment

# Logging
export GRAPH_LOG=debug
export GRAPH_LOG_QUERY_TIMING=gql,sql

# Ethereum
export ETHEREUM_POLLING_INTERVAL=1000
export ETHEREUM_REORG_THRESHOLD=50

# Performance
export GRAPH_ENTITY_CACHE_SIZE=50000
export GRAPH_ETHEREUM_TARGET_TRIGGERS_PER_BLOCK_RANGE=50

# GraphQL
export GRAPH_GRAPHQL_MAX_FIRST=500
export GRAPH_GRAPHQL_QUERY_TIMEOUT=120

​
Production Environment

# Logging
export GRAPH_LOG=info

# High availability
export GRAPH_KILL_IF_UNRESPONSIVE=true
export GRAPH_KILL_IF_UNRESPONSIVE_TIMEOUT_SECS=30

# Ethereum
export ETHEREUM_REORG_THRESHOLD=250
export ETHEREUM_POLLING_INTERVAL=500
export GRAPH_ETHEREUM_TARGET_TRIGGERS_PER_BLOCK_RANGE=100
export GRAPH_ETHEREUM_BLOCK_BATCH_SIZE=20

# Performance
export GRAPH_ENTITY_CACHE_SIZE=100000
export STORE_CONNECTION_POOL_SIZE=25
export GRAPH_STORE_WRITE_BATCH_SIZE=20000

# GraphQL limits
export GRAPH_GRAPHQL_MAX_COMPLEXITY=5000000
export GRAPH_GRAPHQL_MAX_FIRST=1000
export GRAPH_GRAPHQL_MAX_DEPTH=100
export GRAPH_GRAPHQL_QUERY_TIMEOUT=60
export GRAPH_SQL_STATEMENT_TIMEOUT=30

# Query caching
export GRAPH_QUERY_CACHE_BLOCKS=2
export GRAPH_QUERY_CACHE_MAX_MEM=2000

# Load management
export GRAPH_LOAD_THRESHOLD=50
export GRAPH_LOAD_JAIL_THRESHOLD=0.2

​
Query Node

# Node role
export GRAPH_NODE_ID=query-node-1
export DISABLE_BLOCK_INGESTOR=true

# Logging
export GRAPH_LOG=info

# Database
export STORE_CONNECTION_POOL_SIZE=100

# GraphQL
export GRAPH_GRAPHQL_MAX_COMPLEXITY=10000000
export GRAPH_GRAPHQL_MAX_FIRST=1000
export GRAPH_GRAPHQL_QUERY_TIMEOUT=60

# Caching
export GRAPH_QUERY_CACHE_BLOCKS=3
export GRAPH_QUERY_CACHE_MAX_MEM=5000

# Load management
export GRAPH_LOAD_THRESHOLD=100
export GRAPH_LOAD_JAIL_THRESHOLD=0.15

​
Index Node

# Node role
export GRAPH_NODE_ID=index-node-1

# Logging
export GRAPH_LOG=info

# Database
export STORE_CONNECTION_POOL_SIZE=20

# Ethereum
export ETHEREUM_POLLING_INTERVAL=500
export ETHEREUM_REORG_THRESHOLD=250
export GRAPH_ETHEREUM_TARGET_TRIGGERS_PER_BLOCK_RANGE=100
export GRAPH_ETHEREUM_BLOCK_BATCH_SIZE=10

# Performance
export GRAPH_ENTITY_CACHE_SIZE=100000
export GRAPH_STORE_WRITE_BATCH_DURATION=300
export GRAPH_STORE_WRITE_BATCH_SIZE=20000

# IPFS
export GRAPH_IPFS_TIMEOUT=120
export GRAPH_MAX_IPFS_FILE_BYTES=52428800  # 50 MiB

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us