Skip to content

Handle invalid top-level stage code with clearer errors or static diagnostics #2936

@nighca

Description

@nighca

Background

In stage code, users may write statements that look syntactically valid, but are not wrapped inside event handlers such as onStart.

For example, code may be placed directly at the top level of the stage script instead of being registered under an event callback.

Currently, when the project runs, this may lead to runtime failures with error messages that look unrelated to the actual problem. This is confusing because the root cause is the code structure, but the surfaced exception does not clearly explain that.

Image

failure.xbp.zip

What this issue is about

Improve the product behavior when stage code contains top-level statements that are not registered under supported events.

There are two possible improvement directions, and either or both would be valuable:

  • surface a clearer and more relevant error message at runtime
  • detect this pattern earlier through static checking and show diagnostics in the editor before Run

Expected behavior

When users put executable stage code at the top level without wrapping it in onStart or another supported event:

  • the system should not fail with a misleading unrelated exception
  • the user should receive feedback that points to the actual problem
  • ideally, the editor should be able to flag this before runtime

Possible directions

  • improve runtime error mapping so the reported message explains that the code is not placed inside a valid event handler
  • add static analysis / diagnostics for unsupported top-level executable statements in stage code
  • align the diagnostic wording with the mental model users see in the block/event-based editor

Context

This is specifically about cases where the code may appear syntactically fine, but is invalid in the stage-script structure expected by XBuilder.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions