Troubleshooting
How noodle validate reports errors and how to fix the common ones. The self-correcting loop for humans and coding agents.
Noodle Seed is built around a tight repair loop: change server.ts, run noodle validate, read the
error, fix it, repeat. Validation is local and needs no account.
The validate loop
noodle validate # human-readable errors
noodle validate --json # structured errors (for tooling and agents)
noodle validate --fix-prompt # emit a prompt you can hand to a coding agentFix the specific error reported, then re-run. Do not freeform re-edit around a validation error; resolve the one it cites and validate again.
For coding agents
Prefer noodle validate --json to read errors programmatically, or --fix-prompt to get a
ready-to-apply repair prompt. See Build with coding agents. For plugin install,
managed CLI, live readiness, OAuth, or host-rendering failures, use the
developer plugin guide.
Common errors
A smoke command failed
noodle test --json checks registration; add --tool <safe_read> --args <json> to exercise a tool.
An explicitly requested call, including noodle tools call, returns exit code 5 and ok: false if
the protocol/tool fails, the result is incomplete, or the returned data violates the declared output
schema. Inspect error.detail.method and error.detail.reason; error payloads and continuation tokens
are not printed. input_required routes to Devtools for interactive input rather than approving it.
Check application state before retrying a write: an invalid or missing response does not prove rollback.
Diagnose the environment
noodle doctor # checks login, service reachability, project config, and validationnoodle doctor is the fastest way to find a misconfigured project, a missing entrypoint, or a
service/login problem before you deploy.
Runtime version
The CLI requires Node.js 24 LTS or newer. If noodle fails to start, check node --version and
switch with nvm, fnm, mise, or volta, or run any command through npx @noodleseed/one@latest.
Read the logs
Every hosted deployment has a tenant-safe log surface — redacted, bounded, newest-first:
noodle logs # recent records for the linked project
noodle logs --level error # debug | info | warn | error
noodle logs --search "connector" # case-insensitive text match (plain text, not a regex)
noodle logs --since 2026-07-05T00:00:00Z --until 2026-07-05T12:00:00Z
noodle logs --follow # poll for new recordsLogs tell you what your app said while handling requests. For what happened to the requests
(volume, errors, latency, per-tool health), use noodle metrics and noodle events — see
Analytics & observability.
Deploy issues
noodle loginfirst; hosted commands need an authenticated session.- A missing secret or variable referenced by your server fails the deploy closed. Set it with
noodle secrets set/noodle variables setat the right--scope. - Use
noodle inspectandnoodle smoketo check a hosted deployment without exposing secret material.
See the CLI reference for every command and its flags.
Preflight timeouts and service failures
The main deployment preflight has a 75-second client deadline, including upload and response download. The service allows 60 seconds for checking after upload and request validation. Preflight is read-only: if this step fails, publication has not started.
| Result | What to do |
|---|---|
| Missing config or a compile error | Correct the named setting or source error, then validate again. |
deploy_preflight_busy | Another preflight is using that instance's capacity. Honor retryAfterSeconds before one deliberate retry. |
deploy_preflight_timeout or deploy_preflight_transport_failed | Read the audit events before retrying. A missing HTTP response leaves readiness unknown. |
deploy_preflight_service_failed | Include the request ID and elapsed time in your support report. |
Keep the JSON error's requestId, detail.phase, detail.elapsedMs, target, CLI version, and timestamp.
Use the error's next command to read tenant audit events, or select the target explicitly:
noodle audit events --org acme --app support --env prod --jsonMatch the request ID in event details. A deploy.preflight.checked event can show that checking finished
after the client disconnected or after the service deadline. It does not mean publication occurred.
A started event without a completed check is inconclusive; platform support can correlate the request
with infrastructure logs. A client timeout alone cannot establish memory exhaustion. Avoid automatic
deploy retry loops: a later successful attempt can publish the requested version.
Package size
Limits use uncompressed UTF-8 bytes:
| Surface | Limit |
|---|---|
| Whole deploy/preflight request | 32 MiB |
| One compiled React widget | 10 MiB |
| All final widget HTML in one deployment | 20 MiB |
| Raw HTML widget | 256 KiB |
noodle validate enforces widget limits. noodle check reports raw and estimated gzip bundle sizes,
with a recommended 1 MiB performance budget per compiled React widget. Preflight rejects an oversized
request locally with deploy_payload_too_large and names its largest widget bundles. Compression helps
upload time but does not raise the limits.
Keep large media in hosted assets and load dynamic data through bounded tool responses. Sharing a React source component does not remove each tool-linked widget's contribution to the final package. Use the reported compiled sizes when assessing growth; do not edit the generated manifest to work around a limit.