Restate

Restate Documentation Audit

Restate's docs are broad, fresh, and unusually agent-friendly (llms.txt, llms-full.txt, per-page .md exports, an OpenAPI admin spec, even an MCP server card) — but the retry-policy story contradicts itself across three surfaces, the error-code reference links to pages that no longer exist, and the raw .md exports that agents are told to consume are polluted with MDX implementation noise.

1. Default retry behavior contradicts itself across SDK pages, the error-handling guide, and the server-config reference (critical)

Problem: Four SDK error-handling pages (TypeScript, Java, Python, Go — e.g. /develop/ts/error-handling) all state verbatim: "By default, Restate does infinite retries with an exponential backoff strategy." The error-handling guide (/guides/error-handling) says the opposite: "The default retry policy will retry the invocation a limited number of times, after which the invocation will be paused if no progress can be made." The server-config reference (/references/server-config) confirms the limited default: max-attempts default 70, on-max-attempts default pause. The guide then muddies it further with "When a retry policy is unset, Restate by default will retry undefinitely, alike setting max-attempts = "unlimited"" — directly after showing that the default policy pauses after 70 attempts.

Location: /develop/ts/error-handling (and /develop/java, /develop/python, /develop/go equivalents), /guides/error-handling, /references/server-config

Consequence: Retry semantics are the core promise of a durable-execution platform. A developer (or coding agent) reading only the SDK page will design alerting and dead-letter handling around "infinite retries" and never expect invocations to silently pause after ~70 attempts; one reading the guide can't tell whether an unconfigured server retries forever or pauses. Agents consuming llms-full.txt see both claims with equal confidence and will emit whichever they ingested last.

The fix: Pick one canonical statement of the default (70 attempts with exponential backoff, then pause) and propagate it to all four SDK error-handling pages; rewrite or delete the "retry undefinitely" sentence in the guide (it also contains two typos: "undefinitely", "alike setting"), and state explicitly which server versions ship which default.

2. Error Codes reference links to pages that 404 (significant)

Problem: The META0009 entry on /references/errors says "Please look at the Kafka documentation (for TypeScript and Java)". Both URLs return hard 404s with no redirect (verified by HTTP probe); the current Kafka page lives at /services/invocation/kafka. The same reference also points readers hitting non-determinism errors to , which redirects to /tour/microservice-orchestration — a page with no "journaling" section, so the anchor silently evaporates.

Restate Documentation Audit

1. Default retry behavior contradicts itself across SDK pages, the error-handling guide, and the server-config reference (critical)

Location: /develop/ts/error-handling (and /develop/java, /develop/python, /develop/go equivalents), /guides/error-handling, /references/server-config

Snippet	Status	Notes
`npm install --global @restatedev/restate-server@latest @restatedev/restate@latest`	PASS	Installs server 1.7.13 + CLI 1.7.13
`restate --help`	PASS	Prints CLI usage as documented
Download binaries (Linux-x64: curl scarf.sh + `tar -xvf` + `mv` to `$HOME/.local/bin`)	PASS	Works as written; host must have `xz` (tar dependency, had to be installed in sandbox first)
`restate-server --use-random-ports=true --no-logo`	PASS	Server starts on random ports; however ports are NOT "displayed in the first three standard output lines" as claimed — first port appears ~15 lines into the log
Homebrew install (`brew install restatedev/tap/...`)	SKIP	Runtime unavailable (no Homebrew)
Docker run `docker.restate.dev/restatedev/restate:latest`	SKIP	Runtime unavailable (no Docker)
Docker CLI `restate-cli:latest invocations ls`	SKIP	Runtime unavailable (no Docker)
Local CLI commands (`restate whoami`, `restate deployments register localhost:9080`, `restate invocation list`, `restate kv clear`, `restate sql`)	SKIP	Private network target (CLI connects to localhost:9070 admin)

Snippet	Status	Notes
`restate example typescript-hello-world && cd typescript-hello-world && npm install`	PASS	Works in a TTY; in non-interactive shells it fails with `Error: IO error: not a terminal` even with the name supplied — breaks CI/agent use
`npx -y @restatedev/create-app@latest`	PASS	Creates `restate-node-template` directory as documented
`npm run dev`	PASS	`Restate SDK started listening on 9080...`; template `src/app.ts` byte-identical to the docs' CODE_LOAD source
Register deployment (`restate deployments register http://localhost:9080` / `curl localhost:9070/deployments --json ...`)	SKIP	Private network target
`curl localhost:8080/restate/call/Greeter/greet --json '{"name": "Sarah"}'`	SKIP	Private network target
Register-output JSON example (`dp_17szt...` services payload)	PASS	Valid JSON

Snippet	Status	Notes
`openssl genpkey -algorithm ed25519 -outform pem -out private.pem`	PASS	Key generated
`RESTATE_REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE=private.pem` + start server, copy public key from log	PASS	Startup log prints `Loaded request identity key` with `kid: "publickeyv1_..."` exactly as documented

Snippet	Status	Notes
`restate.toml` with `[invocation.default-retry-policy]` + `restate-server --config-file restate.toml`	FAIL	Server starts without warning but ignores the section: `--dump-config` shows default `initial-interval = "500ms"` instead of configured `"50ms"`. Diagnosis: docs bug — the correct section per /references/server-config is top-level `[default-retry-policy]` (verified to apply in a control run). Suggested solution: change the guide's TOML header to `[default-retry-policy]`. Silent misconfiguration — retry limits never take effect
`RESTATE_DEFAULT_RETRY_POLICY__INITIAL_INTERVAL="10s"` etc. env vars	PASS	`--dump-config` reflects 10s / 100 attempts / 10s as set

Check out Manicule.

Restate Documentation Audit

1. Default retry behavior contradicts itself across SDK pages, the error-handling guide, and the server-config reference (critical)

2. Error Codes reference links to pages that 404 (significant)

Runtime snippet checks

Prior reports

Sources

Check out Manicule.

Restate

Restate Documentation Audit

1. Default retry behavior contradicts itself across SDK pages, the error-handling guide, and the server-config reference (critical)

2. Error Codes reference links to pages that 404 (significant)

Runtime snippet checks

Prior reports

Prior reports

Sources

3. The guide's TOML config section doesn't match the configuration reference (significant)

4. The .md exports advertised to agents leak MDX/JSX implementation noise (significant)

5. CLI command grammar drifts between singular and plural across (and within) pages (minor)

6. Two SDKs listed as first-class have no docs pages — llms.txt entries lead to empty exports (minor)

What they do well

Top 3 recommendations

Summary

Required credentials

Pages

https://docs.restate.dev/installation

https://docs.restate.dev/quickstart

https://docs.restate.dev/services/security

https://docs.restate.dev/guides/error-handling

https://docs.restate.dev/services/invocation/kafka

https://docs.restate.dev/schemas/openapi-admin.json

Prior reports