> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt > Use this file to discover all available pages before exploring further. # 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 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. ```bash theme={null} GRAPH_NODE_ID=index-node-1 ``` 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 Node logging configuration Uses same syntax as Rust's [env\_logger](https://docs.rs/env_logger/latest/env_logger/). ```bash theme={null} # 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` Custom log timestamp format Uses [chrono format syntax](https://docs.rs/chrono/latest/chrono/#formatting-and-parsing). ```bash theme={null} GRAPH_LOG_TIME_FORMAT="%Y-%m-%d %H:%M:%S" ``` 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 ```bash theme={null} GRAPH_LOG_QUERY_TIMING=gql,sql ``` Log Proof of Indexing events deterministically Useful for debugging POI-related issues. Kill the process if it becomes unresponsive Set to any value to enable. Timeout in seconds before killing unresponsive node Only used if `GRAPH_KILL_IF_UNRESPONSIVE` is set. ## Ethereum / EVM Chain Configuration Maximum expected reorg size in blocks If a larger reorg occurs, subgraphs may process inconsistent data. ```bash theme={null} ETHEREUM_REORG_THRESHOLD=500 ``` How often to poll Ethereum for new blocks (milliseconds) ```bash theme={null} ETHEREUM_POLLING_INTERVAL=1000 # Poll every 1 second ``` Target number of triggers to process per batch Too small: Excessive requests to Ethereum node Too large: Expensive calls and high memory usage Number of blocks to scan per RPC request when fetching traces Used for call handlers and block handlers with call filters. Number of Ethereum blocks to request in parallel Also limits parallel requests like `trace_filter`. Maximum block range to scan for triggers in each request Maximum range for `eth_getLogs` requests filtering only by event signature (not contract address) Timeout for Ethereum JSON-RPC requests ```bash theme={null} GRAPH_ETHEREUM_JSON_RPC_TIMEOUT=60s ``` 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). Maximum concurrent requests for transaction receipts during block ingestion Fetch transaction receipts in batches instead of concurrently Automatically set to `true` on macOS to avoid DNS issues. Clean up unneeded blocks from the cache **Development only**. In production, causes multiple downloads of the same blocks. Cannot be used with multiple shards. Specify genesis block number Maximum number of contracts to query in a single `eth_getLogs` request Timeout (seconds) for checking `eth_getBlockReceipts` support If timeout occurs, individual transaction receipts are fetched instead. Disable block ingestion Set to `true` to disable, `false` or unset to enable. ```bash theme={null} DISABLE_BLOCK_INGESTOR=true ``` ## Firehose Configuration Maximum size of a message that can be decoded by Firehose ```bash theme={null} GRAPH_NODE_FIREHOSE_MAX_DECODE_SIZE=50MB ``` ## Mapping Handlers Maximum execution time for a mapping handler (seconds) Default: unlimited ```bash theme={null} GRAPH_MAPPING_HANDLER_TIMEOUT=30 ``` Entity cache size in kilobytes Default is 10MB. ```bash theme={null} GRAPH_ENTITY_CACHE_SIZE=50000 # 50MB ``` Maximum supported `apiVersion` in subgraph manifests Subgraphs with higher versions will be rejected. Maximum supported `specVersion` in subgraph manifests Subgraphs with higher versions will be rejected. Maximum WASM runtime stack size Execution stops with an error if exceeded. ```bash theme={null} GRAPH_RUNTIME_MAX_STACK_SIZE=1024KiB ``` ## IPFS Configuration Timeout for IPFS requests (seconds) Includes manifest files and `ipfs.cat` calls from mappings. Maximum file size for `ipfs.cat` calls (bytes) Default: 25 MiB Affects both subgraph files and file data sources. Maximum file size for `ipfs.map` (bytes) Default: 256 MB Entities from `ipfs.map` are kept in memory during processing. Maximum number of files to cache from IPFS Maximum size of each cached IPFS file (bytes) Default: 1 MiB Rate limit for IPFS file data source requests (per second) Maximum retry attempts for IPFS requests Prevents infinite retries on file not found or other errors. File or Redis cache location for IPFS files **Experimental**. Can be: * `redis://host:port` - Redis cache * `/path/to/directory` - Filesystem cache (must be writable) ```bash theme={null} GRAPH_IPFS_CACHE_LOCATION=redis://localhost:6379 GRAPH_IPFS_CACHE_LOCATION=/var/cache/graph-node/ipfs ``` Enable `ipfs.cat` in subgraph mappings **Experimental and non-deterministic**. Will be removed in future versions. ## GraphQL Configuration Maximum GraphQL query execution time (seconds) Default: unlimited ```bash theme={null} GRAPH_GRAPHQL_QUERY_TIMEOUT=60 ``` Maximum GraphQL query [complexity](https://developer.github.com/v4/guides/resource-limitations) Default: unlimited Introspection queries have complexity \~1 million. Set higher than that to allow introspection. ```bash theme={null} GRAPH_GRAPHQL_MAX_COMPLEXITY=10000000 ``` Maximum GraphQL query depth Maximum allowed: 255 Maximum value for `first` argument in queries ```bash theme={null} GRAPH_GRAPHQL_MAX_FIRST=500 ``` Maximum value for `skip` argument in queries Default: unlimited Log warning if GraphQL result exceeds this size (bytes) Default: unlimited ```bash theme={null} GRAPH_GRAPHQL_WARN_RESULT_SIZE=10000000 # 10MB ``` Return error if GraphQL result exceeds this size (bytes) Default: unlimited Checked during response construction to prevent excessive memory use. Port for GraphQL HTTP server Maximum SQL query execution time during GraphQL execution (seconds) Default: unlimited Enable GraphQL specification validations Validates queries follow GraphQL execution rules. Only log GraphQL validation errors without failing queries Only used if `ENABLE_GRAPHQL_VALIDATIONS=true`. Queries may still fail during execution stage. Disable AND/OR filters for performance Useful if complex filters cause performance issues. Disable child-based sorting for performance Useful if child sorting causes performance issues. Token to enable query tracing Requests with `X-GraphTraceQuery` header matching this token will include SQL query traces. ```bash theme={null} GRAPH_GRAPHQL_TRACE_TOKEN=secret-trace-token ``` Then in requests: ```bash theme={null} curl -H "X-GraphTraceQuery: secret-trace-token" http://localhost:8000/subgraphs/name/my-subgraph ``` ### GraphQL Query Caching Subgraphs to cache queries for * `*`: Cache all subgraphs (default) * Comma-separated list: Cache specific subgraphs ```bash theme={null} GRAPH_CACHED_SUBGRAPH_IDS=QmSubgraph1,QmSubgraph2 ``` 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. Maximum memory for query cache (MB) Default: 1 GB Total cache memory is 2x this value (recent blocks + frequent queries). Number of queries after which a cache entry can be considered stale Maximum cache entry size ratio Results larger than (cache shard size / ratio) won't be cached. Set to `0` for no limit. ## Database Configuration Database connection pool size May not be strictly adhered to due to implementation details. Database connection timeout (milliseconds) If exceeded, database is assumed down. Database setup operation timeout (milliseconds) Default: 30 seconds Used for migrations and schema creation, which may take longer than normal operations. Probe interval when database shard is unavailable (seconds) Only one request per interval attempts connection; others fail instantly. PostgreSQL URL for running tests Format: `postgresql://user:password@host:port/database` ```bash theme={null} THEGRAPH_STORE_POSTGRES_DIESEL_URL=postgresql://graph:graph@localhost:5432/graph-test ``` Target duration for batch operations during copying/grafting (seconds) Controls transaction length for long-running operations. 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. Number of parallel workers for batch operations Minimum: 1 Uses idle connections to copy tables in parallel during subgraph copy operations. How long to accumulate changes before writing (seconds) Set to `0` to disable write batching. How many changes to accumulate before writing (kilobytes) Default: 10 MB Set to `0` to disable write batching. 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. Postpone creating attribute-based indexes during subgraph copy Can speed up syncing. 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 History accumulation threshold before pruning Minimum: 1.01 At 1.2, subgraph is pruned when it contains 20% more history than its limit. Prune by copying entities to new tables if removing more than this fraction Must be between 0 and 1, and greater than `DELETE_THRESHOLD`. 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. Minimum blocks to retain for subgraphs with `historyBlocks: auto` Default: 2 × reorg threshold 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 Enable experimental SQL query interface 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](https://thegraph.com/docs/en/indexing/tooling/graph-node/#account-like-optimisation). Reads from `info.table_stats` materialized view (refreshes every 6 hours). Minimum total versions for account-like flagging Required for account-like optimization scan. Maximum unique entities to version ratio Example: 0.01 ≈ 1:100 entity-to-version ratio Required for account-like optimization scan. ## Load Management Load measurement window size (seconds) Used with `GRAPH_LOAD_BIN_SIZE` for load throttling. Load measurement bin size (seconds) Measurements within window are binned into intervals of this size. 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. ```bash theme={null} GRAPH_LOAD_THRESHOLD=100 # Throttle if waits exceed 100ms ``` 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). ```bash theme={null} GRAPH_LOAD_JAIL_THRESHOLD=0.1 # Jail queries using >10% of effort ``` Simulate load management without declining queries Performs all load management steps but only logs decisions instead of rejecting queries. ## Subgraph Features Subgraph version switching behavior * `instant`: Switch immediately when new version deployed * `synced`: Only switch after new deployment syncs (becomes "Pending" version) Starting block for forked subgraph Format: `block_hash:block_number` ```bash theme={null} GRAPH_START_BLOCK=0xabc123...:15000000 ``` API URL for subgraph forking ```bash theme={null} GRAPH_FORK_BASE=https://api.thegraph.com/subgraphs/id/ ``` IPFS hash of subgraph to fork ```bash theme={null} GRAPH_DEBUG_FORK=QmSubgraphHash ``` ## Example Configurations ### Development Environment ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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](/running/docker-setup) - Run Graph Node with Docker * [Configuration Overview](/running/configuration) - Advanced TOML configuration * [Building from Source](/running/from-source) - Compile Graph Node