Environment Variables

Complete reference of all Graph Node environment variables for configuration and tuning

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 instance

Required 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 underscores

Docker 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 configuration

Uses 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 format

Uses chrono format syntax.

GRAPH_LOG_TIME_FORMAT="%Y-%m-%d %H:%M:%S"

GRAPH_LOG_QUERY_TIMING · string

Enable detailed query timing logs

Comma-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 deterministically

Useful for debugging POI-related issues.

GRAPH_KILL_IF_UNRESPONSIVE · boolean

Kill the process if it becomes unresponsive

Set to any value to enable.

GRAPH_KILL_IF_UNRESPONSIVE_TIMEOUT_SECS · number · default: "10"

Timeout in seconds before killing unresponsive node

Only used if GRAPH_KILL_IF_UNRESPONSIVE is set.

Ethereum / EVM Chain Configuration

ETHEREUM_REORG_THRESHOLD · number · default: "250"

Maximum expected reorg size in blocks

If 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 batch

Too 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 traces

Used for call handlers and block handlers with call filters.

ETHEREUM_BLOCK_BATCH_SIZE · number · default: "10"

Number of Ethereum blocks to request in parallel

Also 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 requests

For 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 concurrently

Automatically set to true on macOS to avoid DNS issues.

GRAPH_ETHEREUM_CLEANUP_BLOCKS · boolean

Clean up unneeded blocks from the cache

Development 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 support

If timeout occurs, individual transaction receipts are fetched instead.

DISABLE_BLOCK_INGESTOR · boolean

Disable block ingestion

Set 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 kilobytes

Default is 10MB.

GRAPH_ENTITY_CACHE_SIZE=50000  # 50MB

GRAPH_MAX_API_VERSION · string · default: "0.0.7"

Maximum supported apiVersion in subgraph manifests

Subgraphs with higher versions will be rejected.

GRAPH_MAX_SPEC_VERSION · string · default: "0.0.5"

Maximum supported specVersion in subgraph manifests

Subgraphs with higher versions will be rejected.

GRAPH_RUNTIME_MAX_STACK_SIZE · string · default: "512KiB"

Maximum WASM runtime stack size

Execution 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 MiB

Affects 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 MB

Entities 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 requests

Prevents infinite retries on file not found or other errors.

GRAPH_IPFS_CACHE_LOCATION · string

File or Redis cache location for IPFS files

Experimental. 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 mappings

Experimental 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 complexity

Default: unlimited

Introspection 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 depth

Maximum 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 queries

Default: 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: unlimited

Checked 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 validations

Validates queries follow GraphQL execution rules.

SILENT_GRAPHQL_VALIDATIONS · boolean · default: "true"

Only log GraphQL validation errors without failing queries

Only used if ENABLE_GRAPHQL_VALIDATIONS=true.

Queries may still fail during execution stage.

GRAPH_GRAPHQL_DISABLE_BOOL_FILTERS · boolean

Disable AND/OR filters for performance

Useful if complex filters cause performance issues.

GRAPH_GRAPHQL_DISABLE_CHILD_SORTING · boolean

Disable child-based sorting for performance

Useful if child sorting causes performance issues.

GRAPH_GRAPHQL_TRACE_TOKEN · string

Token to enable query tracing

Requests 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 cache

Set 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 GB

Total 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 ratio

Results 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 size

May 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 seconds

Used 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 tests

Format: 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: unlimited

Should 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 operations

Minimum: 1

Uses 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 MB

Set to 0 to disable write batching.

GRAPH_STORE_DISABLE_CALL_CACHE · boolean · default: "false"

Disable storing/reading eth_call results from cache

Useful 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 copy

Can speed up syncing.

GRAPH_STORE_INSERT_EXTRA_COLS · number · default: "0"

Workaround for ‘too many parameters’ PostgreSQL errors

If 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 pruning

Minimum: 1.01

At 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 fraction

Must 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_THRESHOLD

Must 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: auto

Default: 2 × reorg threshold

GRAPH_REMOVE_UNUSED_INTERVAL · number · default: "360"

How long to wait before removing unused deployments (minutes)

Default: 6 hours

Graph 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 flagging

Required for account-like optimization scan.

GRAPH_STORE_ACCOUNT_LIKE_MAX_UNIQUE_RATIO · number

Maximum unique entities to version ratio

Example: 0.01 ≈ 1:100 entity-to-version ratio

Required 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 queries

When 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 queries

Performs 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 subgraph

Format: 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

• Docker Setup - Run Graph Node with Docker
• Configuration Overview - Advanced TOML configuration
• Building from Source - Compile Graph Node