fix: fall back to manual address when lookup fails

[sam-drumm]

🤖 Raised by an agent from a Sentry issue, following docs/agent/sentry-issue-to-pr.md. Draft until a human has reviewed it.

Sentry

• Issue: https://london-borough-of-hackney.sentry.io/share/issue/c27d051aecec41c8a4c92b8887e4cf0f/
• Event: 2026-09-08T22:58:47Z on /apply/[resident]/address-history
• Fingerprint: TypeError: Cannot read properties of undefined (reading '0')

Issue

A household member typed a non-UK address into the Postcode field and pressed Find address. The breadcrumb shows GET /api/address/… returning 500 with { message: 'Unable to look up address' }, and 11ms later a console TypeError: Cannot read properties of undefined (reading '0') in the minified chunk for pages/apply/[resident]/address-history, followed by the Sentry error event.

The cause is that lookUpAddress never checked res.ok, so it parsed the 500 error body as if it were an AddressLookupResult. The page then read r.address[0]?.UPRN, and optional chaining does not help when address itself is undefined. The surrounding try/catch did send the user on to manual entry, which is why the session continued, but the console.error(e) in that catch still reported the TypeError to Sentry.

Changes

• lib/gateways/internal-api.ts — lookUpAddress now throws when the response is not OK, and encodes the postcode into the URL, so a failed lookup can never be treated as a result.
• pages/apply/[resident]/address-history.tsx — a missing or empty address list now goes straight to manual entry instead of indexing [0], and the catch no longer logs an expected lookup failure as an error.

Together this removes both the client-side throw and the reported Sentry event when Find address receives a 500, or a body with no address array — including overseas or free-text input in the postcode field.

Issues for Review

• The 500 from /api/address/[postcode] itself is untouched. Residents still fall through to manual entry rather than getting a useful message. Worth investigating whether that endpoint should return 400 with { address: [] } for input that is not a UK postcode, ideally validating the postcode shape before calling the lookup API.
• A valid 200 with an empty address array now goes to manual entry rather than rendering an empty select. That looks like the better behaviour, but it is a deliberate change beyond the crash.
• The catch no longer logs anything on that path, so an unrelated error during lookup would also go unreported. Narrowing the catch to lookup failures would be safer.
• ReferenceError: onSystemThemeChanged is not defined appears in the same session but comes from the browser or an extension, not this app. Out of scope.

Steps to Reproduce

1. Sign in as a resident and open a household member's Address history step.
2. Type text that is not a UK postcode into Postcode (for example an overseas address) and press Find address, with /api/address/* answering 500.
3. Watch the browser console.

• Before the fix: TypeError: Cannot read properties of undefined (reading '0') is logged and reported to Sentry.
• After the fix: no TypeError; the What is your address? manual entry form appears with no address select list.

Tests

• Jest — npm test (Jest + tsc --noEmit): 280 passing, including two new lookUpAddress cases in lib/gateways/internal-api.spec.ts.
• New-code coverage — node scripts/agent/new-code-coverage.mjs (≥80% statements and branches on added production source / added lines).
• Cypress with HTTP mocks — npm run e2e:run -- --spec 'cypress/e2e/pages/apply/[resident]/address-history.cy.ts': 3 passing, including the failed-lookup fall back to manual entry.
• Slim CI on sentry/* (Chrome 768×1366): not available to this branch. The run-cypress-e2e-sentry-pr job is added in Build/agent scripts #584 and is not on main yet.
• Human only — LocalStack / local backend (housing-register-local-backend): npm run dev with HOUSING_REGISTER_API pointing at the local API, then the reproduce steps (or npm run e2e:run:local / npm run cypress:open:local when a local spec exists). The implementing agent must not run this.

Agent run

• Implementer model (self-reported): Grok 4.6 (Cursor)
• Reviewer model (self-reported): Claude Sonnet 5 (thinking, high)
• Review verdict: approve, with the non-blocking notes now listed under Issues for Review.
• Cursor chat id: f05c18ec-4631-4c95-9ba0-ef93d7b5af49
• Commits: d03d5594 (fix: fall back to manual address when lookup fails)

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud