Skip to content

Improve unknown-key validation error message in @kbn/config-schema#258633

Merged
hammad-nasir-elastic merged 2 commits intoelastic:mainfrom
hammad-nasir-elastic:fix/improve-config-schema-unknown-key-error-message
Mar 24, 2026
Merged

Improve unknown-key validation error message in @kbn/config-schema#258633
hammad-nasir-elastic merged 2 commits intoelastic:mainfrom
hammad-nasir-elastic:fix/improve-config-schema-unknown-key-error-message

Conversation

@hammad-nasir-elastic
Copy link
Copy Markdown
Contributor

@hammad-nasir-elastic hammad-nasir-elastic commented Mar 19, 2026

resolves issue

Summary

Improves the @kbn/config-schema object.unknown validation error message from the unclear "definition for this key is missing" to a more actionable "Additional properties are not allowed ('<key>' was unexpected)", following OpenAPI-style messaging.

Problem

  • When schema.object() with unknowns: 'forbid' (the default) encounters an unexpected property, the error "definition for this key is missing" is technically correct but not actionable.
  • It does not tell callers that the failure is due to additional properties being disallowed, nor does it name the offending key in the message body.
  • This is especially confusing in API workflows (e.g. Dashboards-as-Code) where users copy GET response payloads into POST/PUT requests and receive cryptic validation errors for response-only fields like meta.

Solution

  • Updated handleError in ObjectType to return "Additional properties are not allowed ('<key>' was unexpected)" for the object.unknown Joi error code, using Joi's child context to include the unexpected property name.
  • Updated 46 test files across the repository that asserted the old error string to match the new message format.
  • All 893 affected Jest tests pass. node scripts/check_changes.ts passes (lint + formatting).

Made with Cursor

The `object.unknown` error from `@kbn/config-schema` previously returned
"definition for this key is missing", which is not actionable. This
changes it to "Additional properties are not allowed ('<key>' was
unexpected)", following OpenAPI-style messaging and including the
unexpected property name. This helps API consumers (e.g. Dashboards-as-
Code workflows) quickly identify which field to remove from their
request payloads.

Made-with: Cursor
@hammad-nasir-elastic hammad-nasir-elastic added Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// release_note:fix backport:skip This PR does not require backporting labels Mar 19, 2026
@hammad-nasir-elastic hammad-nasir-elastic requested review from a team as code owners March 19, 2026 19:28
@hammad-nasir-elastic hammad-nasir-elastic added the Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// label Mar 19, 2026
@hammad-nasir-elastic hammad-nasir-elastic requested review from a team as code owners March 19, 2026 19:28
@hammad-nasir-elastic hammad-nasir-elastic added release_note:fix backport:skip This PR does not require backporting labels Mar 19, 2026
@elasticmachine
Copy link
Copy Markdown
Contributor

Pinging @elastic/kibana-core (Team:Core)

1 similar comment
@elasticmachine
Copy link
Copy Markdown
Contributor

Pinging @elastic/kibana-core (Team:Core)

@hammad-nasir-elastic hammad-nasir-elastic changed the title fix: improve unknown-key validation error message in @kbn/config-schema Improve unknown-key validation error message in @kbn/config-schema Mar 19, 2026
Copy link
Copy Markdown
Contributor

@adcoelho adcoelho left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

response-ops OK 👍

@elasticmachine
Copy link
Copy Markdown
Contributor

💚 Build Succeeded

Metrics [docs]

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id before after diff
lens 2.0MB 2.0MB +113.0B
observability 2.0MB 2.0MB +113.0B
securitySolution 11.3MB 11.3MB +113.0B
stackConnectors 1.4MB 1.4MB +113.0B
total +452.0B

Copy link
Copy Markdown
Contributor

@rylnd rylnd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Detection engine (test) change LGTM! 👍

@TinaHeiligers TinaHeiligers requested review from a team and TinaHeiligers March 20, 2026 19:21
}

protected handleError(type: string, { reason, value }: Record<string, any>) {
protected handleError(type: string, { reason, value, child }: Record<string, any>) {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we please ensure the OAS generation isn't effected by this change.
I don't see how it could, but better to confirm than be surprised later.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looked into this, the OAS generation uses schema conversion (kbn-router-to-openapispec) and does not call handleError; this only affects runtime validation errors.

Additionally I had cursor run the OAS generation script locally for both serverless and traditional (via node scripts/capture_oas_snapshot ... with the same include path list CI uses) and it succeeded.

Copy link
Copy Markdown
Contributor

@jeramysoucy jeramysoucy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kibana security changes LGTM

@hammad-nasir-elastic hammad-nasir-elastic self-assigned this Mar 24, 2026
@hammad-nasir-elastic hammad-nasir-elastic added release_note:skip Skip the PR/issue when compiling release notes and removed release_note:fix labels Mar 24, 2026
@hammad-nasir-elastic hammad-nasir-elastic merged commit 44868bf into elastic:main Mar 24, 2026
21 checks passed
mbondyra added a commit to mbondyra/kibana that referenced this pull request Mar 24, 2026
…ra/kibana into dashboard_align_attachment_to_api

* 'dashboard_align_attachment_to_api' of github.com:mbondyra/kibana: (45 commits)
  [OTel Tracing] HTTP instrumentation (elastic#258663)
  Replace deprecated EUI icons in files owned by @elastic/ml-ui (elastic#255624)
  [Codeowners] add missing codeowners for security_solution_api_integration tests (elastic#259223)
  [CI] fix bad imports that came from a merge-race (elastic#259383)
  Add `.claude/worktrees/` to `.gitignore` (elastic#259192)
  Improve unknown-key validation error message in @kbn/config-schema (elastic#258633)
  [ML] Update Security ML jobs to use entity analytics fields for host and user fields (elastic#255339)
  [Table sweep] Update table columns responsiveness in Index Management and Dashboards (elastic#259340)
  skip failing test suite (elastic#258790)
  skip failing test suite (elastic#259261)
  chore: util to clean cached images (elastic#259335)
  [Entity Store] Use last_seen for automated resolution watermark (elastic#258574)
  [One Workflow] Fix flaky alert trigger Scout test by removing order-dependent assertions (elastic#259299)
  Skip serverless Discover request counts tests for MKI (elastic#259333)
  [Security Solution] render header title in new document flyout in Security Solution and Discover (elastic#258166)
  [Agent Builder] register inference endpoint feature (elastic#259259)
  [Agent Builder] Skills Command Menu - Add descriptions and scope options to agent (elastic#258964)
  [Streams][Streamlang][API] Fully use meta({id}) to reuse schema partials in OAS output (elastic#259275)
  fix(files_example): add tableCaption to EuiInMemoryTable for a11y (elastic#258289)
  [Entity Store] Adding list endpoint with query filter (elastic#258320)
  ...
jeramysoucy pushed a commit to jeramysoucy/kibana that referenced this pull request Mar 26, 2026
…lastic#258633)

resolves
[issue](elastic#249196)

## Summary

Improves the `@kbn/config-schema` `object.unknown` validation error
message from the unclear `"definition for this key is missing"` to a
more actionable `"Additional properties are not allowed ('<key>' was
unexpected)"`, following OpenAPI-style messaging.

### Problem
- When `schema.object()` with `unknowns: 'forbid'` (the default)
encounters an unexpected property, the error `"definition for this key
is missing"` is technically correct but not actionable.
- It does not tell callers that the failure is due to additional
properties being disallowed, nor does it name the offending key in the
message body.
- This is especially confusing in API workflows (e.g.
Dashboards-as-Code) where users copy GET response payloads into POST/PUT
requests and receive cryptic validation errors for response-only fields
like `meta`.

### Solution
- Updated `handleError` in `ObjectType` to return `"Additional
properties are not allowed ('<key>' was unexpected)"` for the
`object.unknown` Joi error code, using Joi's `child` context to include
the unexpected property name.
- Updated 46 test files across the repository that asserted the old
error string to match the new message format.
- All 893 affected Jest tests pass. `node scripts/check_changes.ts`
passes (lint + formatting).


Made with [Cursor](https://cursor.com)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport:skip This PR does not require backporting release_note:skip Skip the PR/issue when compiling release notes Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// v9.4.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Dashboards as code] Improve error messages

10 participants