doc: Add troubleshooting for known issues

[asamal4]

Description

Add troubleshooting for known issues

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up service version
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Unit tests improvement

Tools used to create PR

Identify any AI code assistants used in this PR (for transparency and review context)

• Assisted-by: (e.g., Claude, CodeRabbit, Ollama, etc., N/A if not used)
• Generated by: (e.g., tool name and version; N/A if not used)

Related Tickets & Documents

• Related Issue #
• Closes #

Checklist before requesting a review

• I have performed a self-review of my code.
• PR has passed all pre-merge test jobs.
• If it is a core feature, I have added thorough tests.

Testing

• Please provide detailed steps to perform tests related to this code change.
• How were the fix/results from this change verified? Please provide relevant screenshots or results.

Summary by CodeRabbit

• Documentation
  • Added a new "Troubleshooting" section in the README providing common issues and solutions to help users resolve problems.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Added troubleshooting sections with issue-solution tables to README.md, presented in two locations within the documentation. This is a documentation-only change with no modifications to code logic or exported entities.

Changes

Cohort / File(s)	Summary
Documentation updates README.md	Added "🔧 Troubleshooting" sections containing two-column tables with common issues and their solutions in two separate locations

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change—adding a troubleshooting section for known issues to documentation, matching the actual additions in README.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

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

---

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: 0

🧹 Nitpick comments (1)

README.md (1)

352-358: Troubleshooting section is well-structured and actionable.

The section provides clear, specific solutions to common issues users are likely to encounter:

• The max_tokens guidance with a reference to the configuration file is helpful
• The caching troubleshooting directly addresses the issue and provides two resolution paths

The placement before "Generate answers" and the consistent emoji header style (🔧) align well with the existing README structure.

Note: The troubleshooting coverage is minimal (two entries). Given the framework's complexity across multiple LLM providers, metrics, and configuration options, consider expanding this section in a follow-up to address common setup issues (e.g., missing environment variables, API authentication, script path resolution) or provider-specific gotchas.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 612e95c and e69acb1.

📒 Files selected for processing (1)

• README.md

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
Repo: lightspeed-core/lightspeed-evaluation PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-11T10:05:06.422Z
Learning: Update docs/, README.md, and AGENTS.md when modifying functionality or adding new features

Learnt from: asamal4
Repo: lightspeed-core/lightspeed-evaluation PR: 47
File: src/lightspeed_evaluation/core/output/generator.py:140-145
Timestamp: 2025-09-11T12:47:06.747Z
Learning: User asamal4 prefers that non-critical comments are sent when actual code changes are pushed, not on unrelated commits.

📚 Learning: 2025-12-11T10:05:06.422Z

Learnt from: CR
Repo: lightspeed-core/lightspeed-evaluation PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-11T10:05:06.422Z
Learning: Update docs/, README.md, and AGENTS.md when modifying functionality or adding new features

Applied to files:

• README.md

⏰ 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). (2)

• GitHub Check: tests (3.13)
• GitHub Check: tests (3.12)

🔇 Additional comments (1)

README.md (1)

352-358: Discrepancy: AI summary mentions troubleshooting sections "in two locations" but provided code shows only one.

The annotated code displays a single troubleshooting section at lines 352–358. Please verify whether a second troubleshooting section was added elsewhere in the README that wasn't included in the code review.