Skip to content

Docs/add troubleshooting readme#636

Closed
ankitasahu83964 wants to merge 5 commits into
sreerevanth:mainfrom
ankitasahu83964:docs/add-troubleshooting-readme
Closed

Docs/add troubleshooting readme#636
ankitasahu83964 wants to merge 5 commits into
sreerevanth:mainfrom
ankitasahu83964:docs/add-troubleshooting-readme

Conversation

@ankitasahu83964

@ankitasahu83964 ankitasahu83964 commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Description

Summary

Added a new Troubleshooting section to the README to help users quickly resolve common installation and setup issues.

Changes Made

  • Added troubleshooting guidance for ModuleNotFoundError
  • Added steps to resolve Docker not running issues
  • Added instructions for handling port conflicts
  • Added guidance for Python version mismatch
  • Added setup instructions for missing environment variables

Why

This improves the onboarding experience by providing quick solutions to common setup problems, reducing confusion for new contributors and users.

Fixes #635

Summary by CodeRabbit

  • Documentation

    • Added a new Troubleshooting section after the quick start, with step-by-step fixes for common setup and startup issues (missing packages, Docker not running, port conflicts, Python version mismatches, and missing environment variables).
    • Included practical verification commands to help diagnose problems quickly.
  • Chores

    • Refreshed the contributor acknowledgements and updated contribution statistics and timestamps.

@vercel

vercel Bot commented Jul 16, 2026

Copy link
Copy Markdown

@ankitasahu83964 is attempting to deploy a commit to the sreerevanth's projects Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@ankitasahu83964, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 29 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3c35b425-847a-4f0c-9e1a-349a4ae67675

📥 Commits

Reviewing files that changed from the base of the PR and between 169f179 and de2c99b.

📒 Files selected for processing (1)
  • agentwatch/governance/gdpr.py
📝 Walkthrough

Walkthrough

The README adds troubleshooting instructions for common setup failures. Contributor metadata is refreshed, while memory-erasure formatting and a GDPR module-docstring delimiter are normalized without behavioral changes.

Changes

Troubleshooting documentation

Layer / File(s) Summary
Add troubleshooting guidance
README.md
Documents remedies for missing packages, Docker startup issues, port conflicts, Python version mismatches, and missing environment variables.

Contributor data refresh

Layer / File(s) Summary
Refresh contributor records
agentwatch-landing/public/contributors.json
Replaces contributor entries, updates contribution counts, advances updated_at, and increases total from 24 to 37.

Formatting cleanup

Layer / File(s) Summary
Normalize memory and GDPR formatting
agentwatch/api/server.py, agentwatch/governance/gdpr.py
Reformats memory-erasure errors and predicates, and removes an invisible leading character from the GDPR module docstring without changing behavior.

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

Possibly related PRs

Suggested labels: documentation, Easy

Suggested reviewers: arcgod-design, pavsoss

Poem

I’m a rabbit with a README to share,
Troubleshooting carrots tucked everywhere.
Contributors hop into a refreshed array,
Clean code and new names brighten the day.
Thump, thump—setup troubles fade away!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The PR includes unrelated updates to contributors.json and non-doc formatting changes in server.py and gdpr.py. Move the contributor-data and formatting-only edits into separate PRs so this change stays focused on the README troubleshooting docs.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ 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 is concise and clearly matches the README troubleshooting documentation change.
Linked Issues check ✅ Passed The README adds a troubleshooting section covering all listed installation errors and remedies from #635.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

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

@github-actions

github-actions Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

🧪 PR Test Results

Check Result
Tests (pytest tests/) ✅ success
Lint (ruff check .) ✅ success
Coverage (agentwatch) 74.01%

Python 3.12 · commit de2c99b

@sreerevanth

Copy link
Copy Markdown
Owner

@ankitasahu83964 please fix the ci

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@agentwatch/api/server.py`:
- Around line 1788-1795: Update the identifier comparison in the memory-entry
counting expression to require exact equality with the entry’s user_id, while
preserving the existing empty-value handling and tenant filtering.

In `@agentwatch/governance/gdpr.py`:
- Line 2: Replace the mojibake sequence “—” in the CMP-001 GDPR Data Handling
docstring with the intended em dash character “—”, preserving the surrounding
text.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 948440b1-022d-4c0d-905c-00597c290870

📥 Commits

Reviewing files that changed from the base of the PR and between 393e328 and 169f179.

📒 Files selected for processing (2)
  • agentwatch/api/server.py
  • agentwatch/governance/gdpr.py

Comment thread agentwatch/api/server.py
Comment on lines 1788 to 1795
items = await list_memory_entries()
return sum(
1
for entry in items
if identifier in (entry.get("user_id", "") or "")
and (
self._tenant_id is None
or entry.get("tenant_id") == self._tenant_id
)
and (self._tenant_id is None or entry.get("tenant_id") == self._tenant_id)
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🔴 Critical | ⚡ Quick win

Use exact match instead of substring match for identifiers.

The condition identifier in ... performs a substring match, which can result in incorrectly matching and counting records belonging to other users (e.g., user_1 matching user_123). For GDPR operations, the identifier match must be exact to prevent incorrect reporting or data leakage.

🐛 Proposed fix
         return sum(
             1
             for entry in items
-            if identifier in (entry.get("user_id", "") or "")
+            if identifier == entry.get("user_id")
             and (self._tenant_id is None or entry.get("tenant_id") == self._tenant_id)
         )
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
items = await list_memory_entries()
return sum(
1
for entry in items
if identifier in (entry.get("user_id", "") or "")
and (
self._tenant_id is None
or entry.get("tenant_id") == self._tenant_id
)
and (self._tenant_id is None or entry.get("tenant_id") == self._tenant_id)
)
items = await list_memory_entries()
return sum(
1
for entry in items
if identifier == entry.get("user_id")
and (self._tenant_id is None or entry.get("tenant_id") == self._tenant_id)
)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@agentwatch/api/server.py` around lines 1788 - 1795, Update the identifier
comparison in the memory-entry counting expression to require exact equality
with the entry’s user_id, while preserving the existing empty-value handling and
tenant filtering.

Comment thread agentwatch/governance/gdpr.py
@ankitasahu83964

Copy link
Copy Markdown
Contributor Author

Hi @sreerevanth,

I investigated the CI failures and updated my branch with the latest upstream/main. I also fixed the Ruff formatting issues, so the Python Lint & Type Check now passes.

To verify the remaining failures, I reset my local repository to the latest upstream/main and ran the failing tests again:

git reset --hard upstream/main
pytest tests/test_cli_surface.py::test_cli_surface_is_unchanged

The same test still fails on the latest upstream/main with the CLI surface mismatch (agentwatch compliance commands), and test_sql_store_satisfies_protocol also fails because SqlAlchemyAuditStore cannot be imported.

Since this PR only updates the README documentation, these failures appear to be unrelated to my changes. Could you please confirm whether these existing test failures should be addressed in this PR, or if they belong to the base branch?

@ankitasahu83964

Copy link
Copy Markdown
Contributor Author

Hi @sreerevanth,

I investigated the CI failures and updated my branch with the latest upstream/main. I also fixed the Ruff formatting issues, so the Python Lint & Type Check now passes.

To verify the remaining failures, I reset my local repository to the latest upstream/main and ran the failing tests again:

git reset --hard upstream/main
pytest tests/test_cli_surface.py::test_cli_surface_is_unchanged

The same test still fails on the latest upstream/main with the CLI surface mismatch (agentwatch compliance commands), and test_sql_store_satisfies_protocol also fails because SqlAlchemyAuditStore cannot be imported.

Since this PR only updates the README documentation, these failures appear to be unrelated to my changes. Could you please confirm whether these existing test failures should be addressed in this PR, or if they belong to the base branch?

Screenshot 2026-07-21 113727

@SHAURYASANYAL3 SHAURYASANYAL3 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi! We'd love to get this merged, but it's currently blocked. Please address the following so we can proceed:

  • CI Failures: The following checks are failing: fail, fail, fail. Please check the GitHub Actions tab for detailed logs and apply the necessary fixes.

Let us know once you've updated the PR!

@SHAURYASANYAL3

Copy link
Copy Markdown
Collaborator

Hi! We'd love to get this merged, but it's currently blocked. Please address the following so we can proceed:

  • CI Failures: The following checks are failing: fail, fail, fail. Please check the GitHub Actions tab for detailed logs and apply the necessary fixes.

Let us know once you've updated the PR!

@SHAURYASANYAL3

Copy link
Copy Markdown
Collaborator

Action Required (Update)

🔹 Merge Conflicts: Please pull main and resolve conflicts.

🔹 Review Feedback: Please address previous review comments.

🔹 CI Failures (fail, fail, fail) - Please check Actions tab.

@SHAURYASANYAL3

Copy link
Copy Markdown
Collaborator

Closing this as a duplicate of #650. Please do not open multiple identical PRs. Consider this a friendly warning: spamming duplicate PRs slows down the review process for everyone.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] Add Troubleshooting section for common installation errors

3 participants