feat(requests): record why a request failed

[fallenbagel]

Description

A failed request gives no indication of why it failed. Whether Sonarr was unreachable, the series could not be identified, or its seasons are numbered differently than Sonarr expects, the request looks identical and offers the same unhelpful retry.

Now it records the reason a request failed and clears it when the request is retried. Nothing is displayed differently yet, that follows separately, but the cause is stored per request rather than living only in the server log.

How Has This Been Tested?

• Tested by having a request fail and observing the db column

Screenshots / Logs (if applicable)

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract
• Database migration (if required)

Summary by CodeRabbit

• New Features

  • Media requests now record specific failure reasons, such as unavailable services, dispatch failures, unresolved TVDB IDs, and season-numbering issues.
  • Failure details are stored for future reference.

• Bug Fixes

  • Retrying a failed media request now clears its previous failure reason.
  • Failure reporting is more specific for TV and movie processing issues.

• Tests

  • Added coverage verifying the reported failure reasons for common request failures.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: a60f5d65-aaf3-41f0-8e1d-5663b1516057

📥 Commits

Reviewing files that changed from the base of the PR and between 968d00e and f89740d.

📒 Files selected for processing (7)

• server/constants/media.ts
• server/entity/MediaRequest.ts
• server/migration/postgres/1788991020650-AddFailureReasonToMediaRequest.ts
• server/migration/sqlite/1788990993595-AddFailureReasonToMediaRequest.ts
• server/routes/request.ts
• server/subscriber/MediaRequestSubscriber.test.ts
• server/subscriber/MediaRequestSubscriber.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds classified failure reasons to media requests. It persists the reasons in PostgreSQL and SQLite, records them for Radarr and Sonarr failures, verifies selected cases in tests, and clears the reason when a request is retried.

Changes

Media request failure reasons

Layer / File(s)	Summary
Failure reason contract and persistence server/constants/media.ts, server/entity/MediaRequest.ts, server/migration/...	Adds five failure-reason enum values, a nullable entity field, and PostgreSQL and SQLite migrations.
Failure reason recording and validation server/subscriber/MediaRequestSubscriber.ts, server/subscriber/MediaRequestSubscriber.test.ts	Records dispatch, service, TVDB, and season-numbering failure reasons. Tests verify selected values.
Retry state reset server/routes/request.ts	Clears failureReason before a failed request is retried.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to f8974

Failed media requests now retain a classified failure reason and clear it when retried. The persistence and retry behavior are aligned, with no remaining merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: recording the reason for failed requests.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit hops through records bright
Five failure signs now mark the night
Dispatch and service paths align
TVDB clues are stored in line
A retry clears the old tale
And sends the request along its trail}

_{Comment @coderabbitai help to get the list of available commands.}