Skip to content

docs: describe the install-time 503 and save-before-run - #1120

Merged
nik13 merged 1 commit into
mainfrom
docs/self-hosting-install-initializing-503
Nov 11, 2026
Merged

nik13 merged 1 commit into
mainfrom
docs/self-hosting-install-initializing-503

Conversation

@nik13

@nik13 nik13 commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Summary

This brings docs.futureagi.com in line with two real-user fixes now merged into future-agi/future-agi dev:

Changes

  • self-hosting/helm.mdx, bundled install step: readiness and /health/ mean process health, not a finished install. In releases after v1.58.0, API requests (the UI's included) get the retryable 503 until the migrations are applied.
  • self-hosting/helm.mdx, Troubleshooting: a row for that 503. It points to the bootstrap job's logs and the API's startup_schema_pending log line, and says the API recovers on its own without a restart.
  • prompt/guides/run-a-prompt.mdx: Run waits for a just-made change to save, so it uses what the editor shows.
  • prompt/troubleshooting.mdx: a row for "The prompt changed while saving. Run it again."

The configuration reference page is unchanged. It is generated from deploy/env-reference.toml, which covers keys the compose files read. The chart sets STARTUP_SCHEMA_GUARD_ENABLED internally, and the chart README documents it (updated in #3948).

Dependencies

Both companion PRs are already merged into dev: future-agi/future-agi#3948 (579abc98b0) and future-agi/future-agi#3957 (e5ed4ab0fd). The Helm text says "releases after v1.58.0", because v1.58.0, the latest release, does not include them.

Validation

  • The wording matches the merged code: the message, Retry-After: 5, the 5-second recheck and the startup_schema_pending event in futureagi/tfc/schema_readiness.py and tfc/middleware/schema_readiness.py. The prompt message is in WorkbenchProvider.jsx.
  • The behaviour was observed on a fresh bundled install of the fixed chart on a disposable GCP kind cluster: 810 requests got 503 with Retry-After: 5 during the roughly 9-minute bootstrap, and normal responses afterwards.
  • This PR's checks (link audit and docs build) run in CI.

AI use: Claude Code (Opus 5.5) wrote this change from the merged code and the recorded test evidence. Human review is still required.

🤖 Generated with Claude Code

Helm: while the post-install bootstrap job applies migrations on a bundled
install, pods can be Ready while the install is unfinished. In releases
after v1.58.0 the API answers 503 "The platform is still initializing;
retry shortly." with Retry-After: 5 until the migrations are applied, and
logs startup_schema_pending. Say so in the install step and add a
troubleshooting row.

Prompt: Run Prompt now waits for a just-made change to save, and says
"The prompt changed while saving. Run it again." when the compared
versions change during that wait. Note both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nik13
nik13 merged commit 0a4c486 into main Nov 11, 2026
4 checks passed
@nik13
nik13 deleted the docs/self-hosting-install-initializing-503 branch November 11, 2026 23:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant