docs: improve docs based on Telegram user question analysis#865
Merged
Conversation
Add guidance for diagnosing indexers that stop making progress, covering log checking, RPC issues, dense blocks, handler errors, and memory pressure — based on recurring user questions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add guidance for diagnosing and resolving HTTP 429 errors on hosted GraphQL endpoints, covering plan limits, query frequency, and endpoint security — based on recurring user questions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Clarify the default admin secret for local dev and explain that hosted deployments use a public GraphQL endpoint without auth — a frequent blocker for new users. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document hot reload behavior, what triggers re-indexing, and strategies to iterate faster — including using the testing framework, recent start blocks, and preserving state. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document what happens on each push, re-indexing behavior, adding new chains, zero-downtime updates, and rollback process. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document how to add new chains to existing indexers (cloud and local), performance impact of multi-chain, and zero-downtime deployment behavior. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a migration reference table mapping TheGraph data source templates to Envio's contractRegister pattern for subgraph migrants. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a clear heading for reading on-chain state (eth_call) and a complete webhook/notification example with caching guidance. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summarize key config options affecting performance (preload, unordered mode, field selection) and resource considerations for memory, RPC limits, and database size. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a comparison table of plan tiers, what's included in paid plans, and how to switch plans — reducing the need to leave the docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Cover common causes of missing indexed events: incorrect start block, ABI mismatch, unregistered addresses, RPC issues, and reorgs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughAdds and expands documentation across HyperIndex: migration guidance from TheGraph for dynamic contracts, Effects API examples (eth_call and webhooks with cache guidance), multichain onboarding and performance notes, DB query diagnostics, local dev hot-reload guidance, hosted deployment/billing details, and extended troubleshooting content. Documentation-only changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
docs/HyperIndex/Troubleshoot/common-issues.md (1)
207-207: Optional wording polish for readability.At Line 207, consider replacing “very large datasets” with a more specific phrasing (for example, “large datasets” or “high-volume datasets”).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/HyperIndex/Troubleshoot/common-issues.md` at line 207, Update the wording at the sentence mentioning "very large datasets" (the line that currently reads: "Processing very large datasets or having expensive handler logic...") to use a clearer term such as "large datasets" or "high-volume datasets" for readability, keeping the rest of the sentence intact and preserving the link to the performance optimization guide.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/HyperIndex/Advanced/effect-api.md`:
- Line 73: The heading "Reading On-Chain State (eth_call)" is currently an h3
(###) without an h2 parent; change that heading to an h2 by replacing the
three-pound prefix with two-pound prefix so it becomes a proper subsection
(ensure the line starting with "Reading On-Chain State (eth_call)" uses "##"
instead of "###" to satisfy MD001 and markdown checks).
In `@docs/HyperIndex/Guides/configuration-file.mdx`:
- Around line 307-317: Update the table to add version scope qualifiers for the
version-sensitive options: append a short qualifier like "(applies to v2.x)" or
"(v3: see note)" to the `preload_handlers` and `unordered_multichain_mode`
entries so readers don’t assume they apply to all versions; update the table
cells (either the Option column or the When to use column) for
`preload_handlers` and `unordered_multichain_mode` and add a brief pointer to v3
docs or a note for v3 users (e.g., "applies to v2.x; v3 behavior differs — see
Preload Optimization") to make the version applicability explicit.
In `@docs/HyperIndex/Hosted_Service/hosted-service-billing.mdx`:
- Around line 34-38: Update the billing copy so "Effect API cache support" is
only described as included from Medium plans upward instead of implying it's in
all paid tiers; locate the bullet containing "Effect API cache support for
faster re-indexing" and change the phrasing to something like "Effect API cache
support (Medium plans and up) for faster re-indexing" to match
docs/HyperIndex/Hosted_Service/hosted-service-features.md.
In `@docs/HyperIndex/Troubleshoot/common-issues.md`:
- Around line 256-258: The fenced code block that contains the URL
`https://indexer.dev.hyperindex.xyz/<your-deployment-id>/v1/graphql` is missing
a language tag; update that fence from ``` to ```text (or another appropriate
language like `txt`) so the block is annotated (fixes markdownlint MD040).
- Line 250: Update the documentation sentence that incorrectly references
ENVIO_PG_PASSWORD for configuring the Hasura admin secret: change the variable
name to HASURA_GRAPHQL_ADMIN_SECRET and clarify that this environment variable
(not ENVIO_PG_PASSWORD) should be set before starting the indexer to customize
Hasura admin authentication; ensure the text distinguishes ENVIO_PG_PASSWORD as
Postgres DB credential and only HASURA_GRAPHQL_ADMIN_SECRET as the Hasura admin
secret.
---
Nitpick comments:
In `@docs/HyperIndex/Troubleshoot/common-issues.md`:
- Line 207: Update the wording at the sentence mentioning "very large datasets"
(the line that currently reads: "Processing very large datasets or having
expensive handler logic...") to use a clearer term such as "large datasets" or
"high-volume datasets" for readability, keeping the rest of the sentence intact
and preserving the link to the performance optimization guide.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a3b029da-cf66-44aa-a8ac-158f084cad3d
📒 Files selected for processing (9)
docs/HyperIndex/Advanced/dynamic-contracts.mddocs/HyperIndex/Advanced/effect-api.mddocs/HyperIndex/Advanced/multichain-indexing.mdxdocs/HyperIndex/Advanced/performance/database-performance-optimization.mddocs/HyperIndex/Guides/configuration-file.mdxdocs/HyperIndex/Guides/running-locally.mddocs/HyperIndex/Hosted_Service/hosted-service-billing.mdxdocs/HyperIndex/Hosted_Service/hosted-service-deployment.mddocs/HyperIndex/Troubleshoot/common-issues.md
| }); | ||
| ``` | ||
|
|
||
| ### Reading On-Chain State (eth_call) |
Contributor
There was a problem hiding this comment.
Fix heading-level increment at Line 73.
This heading introduces an h3 level without an h2 parent, which matches the MD001 lint warning and can fail markdown checks.
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 73-73: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/HyperIndex/Advanced/effect-api.md` at line 73, The heading "Reading
On-Chain State (eth_call)" is currently an h3 (###) without an h2 parent; change
that heading to an h2 by replacing the three-pound prefix with two-pound prefix
so it becomes a proper subsection (ensure the line starting with "Reading
On-Chain State (eth_call)" uses "##" instead of "###" to satisfy MD001 and
markdown checks).
Comment on lines
+307
to
+317
| ## Performance Tuning | ||
|
|
||
| Several configuration options affect indexing performance and resource usage. Here's a summary of the key levers: | ||
|
|
||
| | Option | Effect | When to use | | ||
| |---|---|---| | ||
| | `preload_handlers: true` | Batches and pre-fetches data for handlers, significantly speeding up processing | Recommended for most indexers. See [Preload Optimization](/docs/HyperIndex/preload-optimization) | | ||
| | `unordered_multichain_mode: true` | Processes chains in parallel without cross-chain ordering | When you don't need strict cross-chain event ordering | | ||
| | `rollback_on_reorg: false` | Disables reorg handling, reducing overhead | Only if your use case can tolerate occasional stale data during reorgs | | ||
| | Field selection (per event) | Reduces data fetched per event by selecting only needed fields | When you don't need all block/transaction fields | | ||
|
|
Contributor
There was a problem hiding this comment.
Add version scope for config options in this table.
preload_handlers and unordered_multichain_mode are version-sensitive; without a version note, v3 users can interpret these as universally valid current options. Add a short “applies to v2.x” qualifier (or a v3 pointer) in this section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/HyperIndex/Guides/configuration-file.mdx` around lines 307 - 317, Update
the table to add version scope qualifiers for the version-sensitive options:
append a short qualifier like "(applies to v2.x)" or "(v3: see note)" to the
`preload_handlers` and `unordered_multichain_mode` entries so readers don’t
assume they apply to all versions; update the table cells (either the Option
column or the When to use column) for `preload_handlers` and
`unordered_multichain_mode` and add a brief pointer to v3 docs or a note for v3
users (e.g., "applies to v2.x; v3 behavior differs — see Preload Optimization")
to make the version applicability explicit.
Comment on lines
+256
to
+258
| ``` | ||
| https://indexer.dev.hyperindex.xyz/<your-deployment-id>/v1/graphql | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add a language tag to the fenced code block.
The code fence at Line 256 is missing a language identifier (markdownlint MD040).
Suggested fix
-```
+```text
https://indexer.dev.hyperindex.xyz/<your-deployment-id>/v1/graphql</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 256-256: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/HyperIndex/Troubleshoot/common-issues.md` around lines 256 - 258, The
fenced code block that contains the URL
`https://indexer.dev.hyperindex.xyz/<your-deployment-id>/v1/graphql` is missing
a language tag; update that fence from ``` to ```text (or another appropriate
language like `txt`) so the block is annotated (fixes markdownlint MD040).
Add step-by-step troubleshooting for slow GraphQL queries: checking indices, reducing result sets, geographic latency, and WebSocket alternatives. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
DenhamPreen
force-pushed
the
dp/tg-ai-docs-improvements
branch
from
b8caba1 to
adb3fdd
Compare
Use HASURA_GRAPHQL_ADMIN_SECRET instead of ENVIO_PG_PASSWORD for customizing the Hasura admin secret — the latter is for Postgres credentials, not Hasura authentication. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Align billing page with hosted-service-features.md which documents cache support as available on Medium plans and above, not all paid tiers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
keenbeen32
reviewed
Apr 14, 2026
| userAddress: String! @index | ||
| } | ||
| ``` | ||
|
|
Collaborator
There was a problem hiding this comment.
Could be nice to link this page here too, shows how to do composite queries as well:
https://docs.envio.dev/docs/HyperIndex/database-performance-optimization#understanding-database-indices
Collaborator
There was a problem hiding this comment.
Nvm it's literally on that page😂
keenbeen32
reviewed
Apr 14, 2026
|
|
||
| On **Envio Cloud**, this creates a new deployment that re-indexes all chains (including the new one). Your previous deployment continues serving queries with zero downtime until the new deployment is fully synced. See the [deployment guide](../Hosted_Service/hosted-service-deployment.md#updating-your-deployment) for details. | ||
|
|
||
| **Locally**, adding a new chain requires a restart. If you want to avoid re-indexing existing chains from scratch, consider using a recent `start_block` for the new chain during development. |
Collaborator
There was a problem hiding this comment.
Would this not still reindex existing chains just with the new one starting from a later block?
Collaborator
There was a problem hiding this comment.
Donno why it highlighted all of it meant to just be for the locally part
Contributor
Author
There was a problem hiding this comment.
Great feedback thanks, this is misleading
keenbeen32
reviewed
Apr 14, 2026
| ```bash | ||
| pnpm envio stop | ||
| pnpm dev | ||
| ``` |
Collaborator
There was a problem hiding this comment.
I could be wrong but not actually sure this restarts it🤔 Tested it now and it still carried on from the last events processed. Maybe better to just have pnpm envio start -r
Contributor
Author
There was a problem hiding this comment.
pnpm envio stop will kill the docker containers, so should whipe it, but let me test as maybe it's not clearing the volumes however this definitely was the previous behaviour.
keenbeen32
reviewed
Apr 14, 2026
| ```bash | ||
| pnpm envio stop # Removes Docker containers and database | ||
| pnpm dev # Fresh start from start_block | ||
| ``` |
Collaborator
There was a problem hiding this comment.
Same thing, I could be wrong i never use this anyway I always just envio start -r but when i tested it now the stop and dev started from where it left off
keenbeen32
reviewed
Apr 14, 2026
| - Event handler logic | ||
| - Schema (`schema.graphql`) | ||
| - Configuration (`config.yaml`) | ||
| - ABIs or contract addresses |
Collaborator
There was a problem hiding this comment.
Bt of a nitpick but feel like this implies changes to those things trigger the full reindex as opposed to it automatically reindexing on every deployment anyway. Not really important though
keenbeen32
approved these changes
Apr 14, 2026
Replace stop/dev workflow with envio start -r and fix misleading suggestion about avoiding re-indexing when adding chains locally. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Analyzed 66,003 messages across 750 Envio Telegram chats from 904 unique external users to identify the most common documentation gaps. This PR addresses the top 12 pain points with targeted improvements across 9 files.
Changes
Troubleshooting (common-issues.md):
Local Development (running-locally.md):
Deployment (hosted-service-deployment.md):
Advanced Guides:
Configuration & Billing:
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit