Before you begin
- A Forge project deployed to a hosted environment, with at least two releases (deploy a static site or a Go API).
- The project’s git checkout, with the commits those releases were cut from. Suspect commits are read from your local history.
- The
obs:triagepermission to resolve issues (credentials).
RangeError, and release v8.2.0 added a price formatter that throws a TypeError for a plan with no price.
1
List what the newest release opened
obs issues lists the open issues. --since-release keeps only those first seen in one release:terminal
RangeError is listed too, as unresolved. It predates v8.2.0, so this release did not cause it.2
Read the issue
Run this from your checkout, so forge can read the suspect commits from git:
terminal
- at is the culprit: the function and file the error was raised in, after source maps resolved the minified stack.
- first release names the release and the commit range it shipped. This line answers the question.
- by version counts events per build. A browser error reports its frontend build id, so read it against the first release line.
- suspect commits are the commits in that range that touched the culprit’s files and frames. Here both touched
src/App.tsx, but only6d656daetouchedpricing.ts.
--json to hand the whole document, including the latest trace id, to an agent.3
Line it up with what changed
obs changes puts promotions, issues and alerts on one timeline, newest first:terminal
TypeError opened four minutes after v8.2.0 was promoted, and the NewIssue alert followed.4
Fix it and resolve it in the next release
Commit the fix, then mark the issue resolved as of the next release:
terminal
--in next dates the resolve to now. Events from the release that is live now are the bug you are fixing, so they do not reopen the issue. An event from any release promoted after now reopens it as regressed. If the fix already shipped, --in v8.3.0 dates the resolve to just before that release reached the environment.5
Ship the fix and check the issue
Build and promote the fixed release (promote a release):After users load the new release, only the older error is still open, and the fixed one is listed as resolved:The resolved issue counts 7 events, not 5. Two page loads of v8.2.0 arrived after the resolve and did not reopen it. Its timeline in
terminal
terminal
obs issue shows who resolved it and when.What this does not do
- It does not roll anything back. To get back to a good state fast, deploy an earlier release (recover from a bad deploy), then fix forward.
- Suspect commits are a narrowing aid, not blame: they are the commits in the release’s range that touched the files in the stack. A commit that broke a caller in another file is not listed.
- Resolving an issue changes its state only. It does not open a fix. To have an agent investigate new errors, see alerts to GitHub issues: an agent files an investigated issue, and a person decides what happens next.
Troubleshooting
The by-version table shows a hex id instead of a release
The by-version table shows a hex id instead of a release
Browser errors report the frontend’s build id. The first release line maps the issue to the release that shipped that build.
obs check reports INCONCLUSIVE no_request_telemetry for a frontend-only release
obs check reports INCONCLUSIVE no_request_telemetry for a frontend-only release
For a release of a static site with no backend,
obs check can return this even though the release opened an issue. Use obs issues --since-release to see what the release introduced.Next steps
Go from an error to a reviewed fix
Turn the issue into an agent-written pull request, with a person approving at each step.
Debug production with an AI agent
Give an agent the same
obs documents, plus logs and traces.How release verdicts work
How
obs check judges a promotion before and after.Send OpenTelemetry from any app
Get the same issues for an app Forge does not deploy.
Dashboards and alerts
Source maps, issue states and the
NewIssue and IssueRegressed alerts.Querying with forge obs
Every
obs verb, its JSON output and exit codes.