Add a blog post about improved error handling for oauth2 configuration without internet

[wmoss]

Proposed change

Add a blog post about improved error handling for oauth2 configuration without internet

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request: Fix account link no internet on startup core#154579

Summary by CodeRabbit

• Documentation
  • Published a blog post describing improved OAuth2 config error handling when the internet is unavailable, documenting prior behavior, a migration pattern to surface transient failures as retryable, before/after examples, and notes on how the project’s scaffolding will generate the new handling for future integrations.

[wmoss]

Once home-assistant/core#154579 merges and I'm able to put up the migration PRs, I can update this to add links to example migration PRs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a blog post documenting a migration to catch ImplementationUnavailableError from async_get_config_entry_implementation and re-raise it as ConfigEntryNotReady so OAuth2 config flows become retryable when the internet is unavailable.

Changes

Cohort / File(s)	Summary
Blog documentation blog/2025-10-26-config-entry-oauth2-error-handling.md	New blog post describing historical behavior where async_get_config_entry_implementation raised a non-retryable ImplementationUnavailableError, the migration pattern to wrap it in try/except and re-raise ConfigEntryNotReady, before/after code examples, and note that new scaffolds include the try/except.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant User
participant ConfigFlow
participant ImplementationLookup as async_get_config_entry_implementation
participant Core

rect rgba(220,235,255,0.6)
Note over ConfigFlow,ImplementationLookup: Before
ConfigFlow->>ImplementationLookup: request implementation
ImplementationLookup-->>ConfigFlow: raises ImplementationUnavailableError
ConfigFlow-->>Core: fails (non-retryable error)
end

rect rgba(220,255,220,0.6)
Note over ConfigFlow,ImplementationLookup: After (wrapped)
ConfigFlow->>ImplementationLookup: request implementation (try)
ImplementationLookup-->>ConfigFlow: raises ImplementationUnavailableError
ConfigFlow->>ConfigFlow: catch ImplementationUnavailableError\nraise ConfigEntryNotReady
ConfigFlow-->>Core: raises ConfigEntryNotReady (retryable)
Core-->>ConfigFlow: scheduled retry
end

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

• Check markdown formatting and front-matter
• Verify code examples compile/accurately reflect APIs and exception names
• Confirm links/references to issues and PRs are correct and styled consistently

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "Add a blog post about improved error handling for oauth2 configuration without internet" accurately and clearly summarizes the main change in the pull request. According to the raw summary, this PR adds a new blog post documenting improved error handling for OAuth2 configuration when the internet is unavailable, which directly aligns with the title. The title is specific, concise, and provides meaningful information about what the changeset introduces without being overly broad or vague.
Description Check	✅ Passed	The PR description follows the required template structure and includes all major sections with appropriate content. The "Type of change" section has the correct box checked for documenting a new or changing feature. Both checklist items are marked as completed, indicating the author followed documentation guidelines and verified rendering. The "Additional information" section includes a link to the related core PR (home-assistant/core#154579). The "Proposed change" section is brief but on-topic, and the empty "fixes #" field appears intentional since the PR description notes it does not cite an issue.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between 0f8d9ff and 7986458.

📒 Files selected for processing (1)

• blog/2025-10-26-config-entry-oauth2-error-handling.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

*/**(html|markdown|md)

⚙️ CodeRabbit configuration file

*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.

• Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
• In step-by-step instructions, front the location phrase in the instructional sentence.
• In step-by-step instructions, front the 'goal' in the instructional sentence.
• In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
• do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'

*/**(html|markdown|md): - Use bold to mark UI strings.

• If "" are used to mark UI strings, replace them by bold.

• Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"

• Use sentence-style capitalization also in headings.

do not comment on HTML used for icons

Avoid flagging inline HTML for embedding videos in future reviews for this repository.

Files:

• blog/2025-10-26-config-entry-oauth2-error-handling.md

🔇 Additional comments (1)

blog/2025-10-26-config-entry-oauth2-error-handling.md (1)

7-22: Blog post content looks solid.

The explanation is clear and direct, properly guides integrations through the migration pattern, and the code example effectively demonstrates the required changes. The references to related issues and the core PR provide good context.

---

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

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

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between fdacf2c and c045f47.

📒 Files selected for processing (1)

• blog/2025-10-26-config-entry-aouth2-error-handling.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

*/**(html|markdown|md)

⚙️ CodeRabbit configuration file

*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.

• Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
• In step-by-step instructions, front the location phrase in the instructional sentence.
• In step-by-step instructions, front the 'goal' in the instructional sentence.
• In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
• do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'

*/**(html|markdown|md): - Use bold to mark UI strings.

• If "" are used to mark UI strings, replace them by bold.

• Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"

• Use sentence-style capitalization also in headings.

do not comment on HTML used for icons

Avoid flagging inline HTML for embedding videos in future reviews for this repository.

Files:

• blog/2025-10-26-config-entry-aouth2-error-handling.md

🪛 markdownlint-cli2 (0.18.1)

blog/2025-10-26-config-entry-aouth2-error-handling.md

22-22: Link text should be descriptive

(MD059, descriptive-link-text)

---

22-22: Link text should be descriptive

(MD059, descriptive-link-text)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Redirect rules - developers-home-assistant
• GitHub Check: Header rules - developers-home-assistant
• GitHub Check: Pages changed - developers-home-assistant

[wmoss]

@coderabbitai generate docstrings

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

blog/2025-10-26-config-entry-oauth2-error-handling.md (1)

1-1: Filename appears to have been corrected.

The past review flagged a filename typo ("aouth2" → "oauth2"). The current file_start shows the corrected name. If this hasn't been committed yet, ensure the file is renamed to blog/2025-10-26-config-entry-oauth2-error-handling.md.

🧹 Nitpick comments (1)

blog/2025-10-26-config-entry-oauth2-error-handling.md (1)

11-11: Use more direct phrasing.

Per documentation guidelines, use a direct, authoritative tone. Change "Here is an example of the migration," to a more directive phrasing.

-Here is an example of the migration,
+To migrate the code, apply the following change:

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between c045f47 and 0f8d9ff.

📒 Files selected for processing (1)

• blog/2025-10-26-config-entry-oauth2-error-handling.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

*/**(html|markdown|md)

⚙️ CodeRabbit configuration file

*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.

• Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
• In step-by-step instructions, front the location phrase in the instructional sentence.
• In step-by-step instructions, front the 'goal' in the instructional sentence.
• In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
• do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'

*/**(html|markdown|md): - Use bold to mark UI strings.

• If "" are used to mark UI strings, replace them by bold.

• Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"

• Use sentence-style capitalization also in headings.

do not comment on HTML used for icons

Avoid flagging inline HTML for embedding videos in future reviews for this repository.

Files:

• blog/2025-10-26-config-entry-oauth2-error-handling.md

[coderabbitai]

✅ Actions performed

Initiated docstring generation; will generate only if new commits exist.

[coderabbitai]

Caution

Docstrings generation - FAILED

No docstrings were generated.