Skip to content

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

Description

@shiju-nv

User Story

I use OpenShell and have encountered an opaque error from openshell-gateway config preflight while checking a gateway configuration. I need the diagnostic to identify the rejected key and its line so I can correct the file without exposing configuration values in logs.

Problem Statement

An unknown bare TOML key in a schema-2 gateway file produces a generic preflight diagnostic containing category=malformed detected_version=2. The diagnostic omits the rejected key and its line.

Impact / Why This Matters

The current workaround is to inspect the TOML manually or compare its keys with the documented schema. The preflight failure gives no location to narrow that search, including when a removed key remains after an upgrade.

Acceptance Criteria

  • An unknown bare key produces its name and one-based line number in the preflight diagnostic. The example below identifies guest_tls_cert on line 5.
  • An unknown quoted key reports its line without its contents. Diagnostics omit configuration values and quoted key text, including escaped control characters.
  • Line numbers remain correct with CRLF line endings and preceding Unicode text.
  • Existing error categories, version reporting and file-preservation behavior remain intact.

Reproduction Steps

  1. Save this as gateway.toml:

    [openshell]
    version = 2
    
    [openshell.gateway]
    guest_tls_cert = 'example-value'
  2. With openshell-gateway built from the inspected main revision, run:

    openshell-gateway config preflight --path gateway.toml
  3. Check the failure diagnostic. The current source formats it as category=malformed detected_version=2, with no key name or line number. The file should remain unchanged.

Suggested UX (if applicable)

For the bare key above, a suffix such as unknown_field=guest_tls_cert line=5 would identify the problem. For a quoted key, use a line-only suffix such as unknown_field line=<line>. Keep configuration values out of the diagnostic.

Environment

  • Main source inspected: a2afbcdc4ef39f9b29477a548580b0262b90c96f (November 5, 2026).
  • Latest stable source inspected: v0.1.7, commit 5d25211b25a8fc887e8d5c606d57d6ab22f1d76c, published November 3, 2026.
  • Deployment: local gateway configuration preflight.

Logs

Activity

  1. added theissue type on Nov 5, 2026
  2. added
    area:platformSDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.
    topic:operabilityInstalling/configuring deployments, upgrades, backup/restore, diagnostics, and maintenance.
    topic:uxCLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience.
    on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

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

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions