Skip to content

fix(gateway): name unknown config keys in preflight failures - #5320

Open
shiju-nv wants to merge 2 commits into
ai-openshell:mainfrom
shiju-nv:fix/5308-preflight-unknown-key/shiju-nv
Open

shiju-nv wants to merge 2 commits into
ai-openshell:mainfrom
shiju-nv:fix/5308-preflight-unknown-key/shiju-nv

Conversation

@shiju-nv

@shiju-nv shiju-nv commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

If a typo or an old setting makes openshell-gateway config preflight fail, the error can now point you to the line to fix. For example, if the removed guest_tls_cert setting is still on line 5 of gateway.toml after an upgrade, you'll see unknown_field=guest_tls_cert line=5.

Related Issue

Closes #5308. This also addresses the unknown-key error reported in #3959.

Changes

  • Show the name and line number when the parser can pinpoint an unknown unquoted TOML key. For a quoted key, show only the line number. Keep config values out of the error.
  • Use the generic error when the parser can only point to the whole table. Document what to expect in the gateway config guide.
  • Include the error category and detected schema version in the message. Preflight leaves the config file untouched.

Release Notes

Testing

Eight focused openshell-server library tests passed. They cover the preflight CLI and runtime behavior, including quoted keys, escaped characters, Unicode with CRLF line endings, and errors that point to the whole table. A separate caller compiled using the existing two-field ConfigFileError::Parse constructor.

Server Clippy passed for all targets with warnings denied. Formatting and whitespace checks passed, along with the SPDX and changed Markdown checks. mise run docs passed with three warnings and a passing navigation check. GitHub Branch Checks passed on 0d13466.

  • Checks appropriate to the affected code and behavior pass
  • Unit tests added/updated
  • E2E tests added/updated (not applicable to this diagnostic change)

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

@shiju-nv shiju-nv added the area:platform SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management. label Nov 6, 2026
@purp purp added topic:operability Installing/configuring deployments, upgrades, backup/restore, diagnostics, and maintenance. topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience. labels Nov 15, 2026
@shiju-nv shiju-nv added topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience. and removed topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience. labels Nov 22, 2026
@github-actions
github-actions Bot requested a review from purp November 22, 2026 09:30

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:platform SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management. topic:operability Installing/configuring deployments, upgrades, backup/restore, diagnostics, and maintenance. topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(gateway): identify unknown bare keys in config preflight errors

2 participants