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, including 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.
  • Improved handling prevents conflicting TVDB assignments and excludes empty TV seasons from all-season requests.

• Tests

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

[coderabbitai]

Important

Review skipped

The saved review history does not include the base for the last reviewed commit. This saved history cannot establish the base for an incremental review. Comment @coderabbitai full review to establish a new review baseline. No full review was started, and the last reviewed checkpoint was preserved.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

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: 777d214a-56ff-42b9-a7ab-a4deb6769906

📥 Commits

Reviewing files that changed from the base of the PR and between a48b7bf and 04553d6.

📒 Files selected for processing (1)

• server/entity/MediaRequest.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, persists them in PostgreSQL and SQLite, records them for Radarr and Sonarr failures, handles TVDB conflicts, and clears the reason on retry.

Changes

Media request changes

Layer / File(s)	Summary
Failure reason contract and persistence server/constants/media.ts, server/entity/MediaRequest.ts, server/migration/...	Adds five failure-reason values, a nullable entity field, and PostgreSQL and SQLite migrations.
Conflict-tolerant media persistence server/entity/MediaRequest.ts	Checks TVDB ownership before clearing a conflicting identifier and rethrows unrelated save failures.
Failure recording and retry reset server/subscriber/MediaRequestSubscriber.ts, server/subscriber/MediaRequestSubscriber.test.ts, server/routes/request.ts	Records failure reasons, verifies selected values, and clears the reason before retry.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant MediaRequestSubscriber
  participant MediaRequest
  participant MediaRequestDatabase
  participant RequestRoute
  MediaRequestSubscriber->>MediaRequest: Set failureReason and failed status
  MediaRequest->>MediaRequestDatabase: Save failure reason
  RequestRoute->>MediaRequest: Clear failureReason on retry
  MediaRequest->>MediaRequestDatabase: Save re-approved request

Loading

Suggested reviewers: xyerophyte

Merge Risk: 🟡 Moderate · up to 04553

A failed media save can discard a valid TVDB association when another row has the same identifier, risking incorrect media linkage; this should be fixed before merge.

🚥 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 failure reasons for requests.

---

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

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

[github-actions]

This pull request has merge conflicts. Please resolve the conflicts so the PR can be successfully reviewed and merged.