Docs issues
# Docs issues
> Where the official Farcaster and Snapchain docs are out of date or wrong.
The official docs had these outdated or wrong statements when the pages were last read, on 2026-10-18. Code references are to Snapchain v0.14.3 (`fc87f26`). [DOCS_ISSUES.md](https://github.com/sudharshanx/runfarcaster/blob/main/DOCS_ISSUES.md) has, for each problem, the page, what it says, what the check found and how it was checked.
## Snapchain docs and repo
| # | Page | Issue |
|---|---|---|
| 1 | [running-a-node](https://snapchain.farcaster.xyz/guides/running-a-node) | Firewall image opens gossip 3382 on TCP; gossip is QUIC over **UDP** 3382 |
| 2 | running-a-node | "Allow SSH from Anywhere", redundant `mkdir snapchain`, manual Docker install the bootstrap already does |
| 3 | Getting Started vs README | Disk: 2 TB vs 1.5 TB. Measured: 557.86 GB DB, 699 GB peak with this guide's space saver |
| 4 | README | "Ports 3381 - 3383 exposed on both TCP and UDP."; compose publishes only 3381/tcp, 3382/udp, 3383/tcp |
| 5 | [HTTP API](https://snapchain.farcaster.xyz/reference/httpapi/httpapi) | Paging example uses `reverse=1` (rejected); JS example uses the wrong page-token parameter |
| 6 | HTTP API reference | `/v1/signersByFid` and `/v1/signer` are missing; they return gasless keys and `currentUserNonce` |
| 7 | (undocumented) | `requesterFids` needs `[]` brackets over HTTP |
| 8 | [writing-messages](https://snapchain.farcaster.xyz/guides/writing-messages) | Example logs the private key |
| 9 | writing-messages | Suggests 9 scopes and a 30-day TTL; fewer scopes and a shorter TTL are safer (suggestion) |
| 12 | Getting Started | Bootstrap needs a TTY and never returns; not documented |
| 13 | managing-a-node | FID 0 needs `SKIP_CRONTAB=true` (now fixed in the docs) |
| 14 | managing-a-node | Grafana 3000 published on all interfaces with `admin:admin` (mostly fixed) |
| 16 | Getting Started | No mention of provider quotas; Hetzner new accounts cap volumes at 1024 GB |
| 17 | Getting Started | Snapshot restore keeps chunks + tar + DB until the end; explains the 1.5 to 2 TB figure but no doc says so |
| 29 | writing-messages | Imports from `@farcaster/hub-web` with gRPC `hub-nodejs` code (likely; snippet not run) |
| 31 | several | Leftover "Hub"/"Hubble" wording; logo alt text copied from the firewall image |
| 32 | [Casts](https://snapchain.farcaster.xyz/reference/httpapi/casts) | `castsByParent` never returns an empty `nextPageToken`: the last page carries `[null,null]` (base64), and sending it starts over ([Recipes](https://sudharshanx.github.io/runfarcaster/recipes/#read-the-replies-to-a-cast)) |
| 33 | HTTP API | On endpoints that read every shard (`castsByParent`, `reactionsByCast`, `linksByTargetFid`), `pageSize` applies per shard: `pageSize=2` returned 4 messages |
| 34 | [User data](https://snapchain.farcaster.xyz/reference/httpapi/userdata) | `user_data_type` is ignored over HTTP; every field comes back |
| 35 | [Reactions](https://snapchain.farcaster.xyz/reference/httpapi/reactions) | `reaction_type` takes `Like`/`Recast`; the enum names the responses use (`REACTION_TYPE_LIKE`) get HTTP 400 |
| 36 | (undocumented) | A snapshot replaced during the restore makes the node crash on a 404, then run without that shard |
## docs.farcaster.xyz
| # | Page | Issue |
|---|---|---|
| 10 | [Hello World](https://docs.farcaster.xyz/developers/guides/basics/hello-world) | Adds the app key onchain with ~$10 of OP ETH; gasless `KEY_ADD` replaced that on mainnet with V16 on 2026-05-07 (`src/version/version.rs`; the writing-messages guide was updated in docs PR #989) |
| 11 | [Architecture overview](https://docs.farcaster.xyz/learn/architecture/overview) | Lists adding keys as onchain-only; no validators vs read nodes |
| 18 | Create an account key | Onchain KeyGateway only |
| 19 | Accounts | Keys "managed by the KeyRegistry"; links the deprecated onchain-signers endpoint |
| 20 | Messages | "Hub" wording; storage limits and price out of date |
| 21 | Get account messages | Uses `apps/hubble`, which no longer exists |
| 22 | Apps | Dead Replicator link (now `packages/shuttle`) |
| 23 | Signer Requests | Describes onchain registration only (low confidence) |
## hub-monorepo and mirrors
| # | Page | Issue |
|---|---|---|
| 15 | `@farcaster/core` | Needs a `Buffer` polyfill in browsers; ships `@faker-js/faker` as a runtime dependency |
| 24 | hub-monorepo README | Describes an `/apps/` folder that does not exist |
| 25 | hub-nodejs README | Hubble framing, dead doc links |
| 26 | hub-nodejs Builders.md | Documents removed `makeSignerAdd`; omits `makeKeyAdd*` builders |
| 27 | hub-web README | Old port 2281, broken axios example, dead link |
| 28 | hello-world example | Onchain signer; README names the wrong folder |
| 30 | Neynar Snapchain mirror | Still teaches the onchain signer flow |
Sources: [SOURCES.md](https://github.com/sudharshanx/runfarcaster/blob/main/SOURCES.md).
## How this guide differs from the official one
| Topic | Official guide ([running-a-node](https://snapchain.farcaster.xyz/guides/running-a-node), [Getting Started](https://snapchain.farcaster.xyz/getting-started)) | This guide |
|---|---|---|
| Server | Set up by hand in the AWS console, with screenshots | `provision.sh` on Hetzner |
| Cost | "Roughly $100/month", an estimate | $0.164 an hour and $2.31 until synced (one run, estimated from list prices) |
| Time to sync | "A few hours" | About 14 hours on cax31 |
| Disk | 2 TB (docs), 1.5 TB (README) | 1000 GB worked with two helper scripts; `node.sh` now installs them (unit-tested only) |
| Firewall | Opens 3382/**tcp** and SSH to everyone ([Docs issues #1, #2](https://sudharshanx.github.io/runfarcaster/docs-issues/)) | 3382/udp; SSH only from `SSH_SOURCE_CIDRS`; 3381 and 3383 closed |
| Bootstrap | `curl … \| bash`, needs a terminal, keeps running in front of you | The same official script, run by `node.sh`, which then waits for sync |
| API keys | Points to a paid API service for speed | None; the app reads from your node |
| App keys | hello-world still adds keys onchain with about $10 of OP ETH ([Docs issues #10](https://sudharshanx.github.io/runfarcaster/docs-issues/)) | Gasless `KEY_ADD` (`src/core/validations/key.rs`, live since V16 per `src/version/version.rs`) |
| Posting | Older pages send messages to a hosted hub | Your read node sends them on (`submit_message_internal` in `src/network/server.rs`, `ReadNodeMempool` in `src/mempool/mempool.rs`) |
| Cleanup | Not covered | `teardown.sh` (not yet run on real servers) |
Where the official Farcaster and Snapchain docs are out of date or wrong.
The official docs had these outdated or wrong statements when the pages were last read, on 2026-10-18. Code references are to Snapchain v0.14.3 (fc87f26). DOCS_ISSUES.md has, for each problem, the page, what it says, what the check found and how it was checked.
Snapchain docs and repo
Section titled “Snapchain docs and repo”| # | Page | Issue |
|---|---|---|
| 1 | running-a-node | Firewall image opens gossip 3382 on TCP; gossip is QUIC over UDP 3382 |
| 2 | running-a-node | “Allow SSH from Anywhere”, redundant mkdir snapchain, manual Docker install the bootstrap already does |
| 3 | Getting Started vs README | Disk: 2 TB vs 1.5 TB. Measured: 557.86 GB DB, 699 GB peak with this guide’s space saver |
| 4 | README | “Ports 3381 - 3383 exposed on both TCP and UDP.”; compose publishes only 3381/tcp, 3382/udp, 3383/tcp |
| 5 | HTTP API | Paging example uses reverse=1 (rejected); JS example uses the wrong page-token parameter |
| 6 | HTTP API reference | /v1/signersByFid and /v1/signer are missing; they return gasless keys and currentUserNonce |
| 7 | (undocumented) | requesterFids needs [] brackets over HTTP |
| 8 | writing-messages | Example logs the private key |
| 9 | writing-messages | Suggests 9 scopes and a 30-day TTL; fewer scopes and a shorter TTL are safer (suggestion) |
| 12 | Getting Started | Bootstrap needs a TTY and never returns; not documented |
| 13 | managing-a-node | FID 0 needs SKIP_CRONTAB=true (now fixed in the docs) |
| 14 | managing-a-node | Grafana 3000 published on all interfaces with admin:admin (mostly fixed) |
| 16 | Getting Started | No mention of provider quotas; Hetzner new accounts cap volumes at 1024 GB |
| 17 | Getting Started | Snapshot restore keeps chunks + tar + DB until the end; explains the 1.5 to 2 TB figure but no doc says so |
| 29 | writing-messages | Imports from @farcaster/hub-web with gRPC hub-nodejs code (likely; snippet not run) |
| 31 | several | Leftover “Hub”/“Hubble” wording; logo alt text copied from the firewall image |
| 32 | Casts | castsByParent never returns an empty nextPageToken: the last page carries [null,null] (base64), and sending it starts over (Recipes) |
| 33 | HTTP API | On endpoints that read every shard (castsByParent, reactionsByCast, linksByTargetFid), pageSize applies per shard: pageSize=2 returned 4 messages |
| 34 | User data | user_data_type is ignored over HTTP; every field comes back |
| 35 | Reactions | reaction_type takes Like/Recast; the enum names the responses use (REACTION_TYPE_LIKE) get HTTP 400 |
| 36 | (undocumented) | A snapshot replaced during the restore makes the node crash on a 404, then run without that shard |
docs.farcaster.xyz
Section titled “docs.farcaster.xyz”| # | Page | Issue |
|---|---|---|
| 10 | Hello World | Adds the app key onchain with ~$10 of OP ETH; gasless KEY_ADD replaced that on mainnet with V16 on 2026-05-07 (src/version/version.rs; the writing-messages guide was updated in docs PR #989) |
| 11 | Architecture overview | Lists adding keys as onchain-only; no validators vs read nodes |
| 18 | Create an account key | Onchain KeyGateway only |
| 19 | Accounts | Keys “managed by the KeyRegistry”; links the deprecated onchain-signers endpoint |
| 20 | Messages | “Hub” wording; storage limits and price out of date |
| 21 | Get account messages | Uses apps/hubble, which no longer exists |
| 22 | Apps | Dead Replicator link (now packages/shuttle) |
| 23 | Signer Requests | Describes onchain registration only (low confidence) |
hub-monorepo and mirrors
Section titled “hub-monorepo and mirrors”| # | Page | Issue |
|---|---|---|
| 15 | @farcaster/core | Needs a Buffer polyfill in browsers; ships @faker-js/faker as a runtime dependency |
| 24 | hub-monorepo README | Describes an /apps/ folder that does not exist |
| 25 | hub-nodejs README | Hubble framing, dead doc links |
| 26 | hub-nodejs Builders.md | Documents removed makeSignerAdd; omits makeKeyAdd* builders |
| 27 | hub-web README | Old port 2281, broken axios example, dead link |
| 28 | hello-world example | Onchain signer; README names the wrong folder |
| 30 | Neynar Snapchain mirror | Still teaches the onchain signer flow |
Sources: SOURCES.md.
How this guide differs from the official one
Section titled “How this guide differs from the official one”| Topic | Official guide (running-a-node, Getting Started) | This guide |
|---|---|---|
| Server | Set up by hand in the AWS console, with screenshots | provision.sh on Hetzner |
| Cost | “Roughly $100/month”, an estimate | $0.164 an hour and $2.31 until synced (one run, estimated from list prices) |
| Time to sync | “A few hours” | About 14 hours on cax31 |
| Disk | 2 TB (docs), 1.5 TB (README) | 1000 GB worked with two helper scripts; node.sh now installs them (unit-tested only) |
| Firewall | Opens 3382/tcp and SSH to everyone (Docs issues #1, #2) | 3382/udp; SSH only from SSH_SOURCE_CIDRS; 3381 and 3383 closed |
| Bootstrap | curl … | bash, needs a terminal, keeps running in front of you | The same official script, run by node.sh, which then waits for sync |
| API keys | Points to a paid API service for speed | None; the app reads from your node |
| App keys | hello-world still adds keys onchain with about $10 of OP ETH (Docs issues #10) | Gasless KEY_ADD (src/core/validations/key.rs, live since V16 per src/version/version.rs) |
| Posting | Older pages send messages to a hosted hub | Your read node sends them on (submit_message_internal in src/network/server.rs, ReadNodeMempool in src/mempool/mempool.rs) |
| Cleanup | Not covered | teardown.sh (not yet run on real servers) |