docs: add Brev troubleshooting guide#2722
Conversation
docs(get-started): add Brev troubleshooting guide Signed-off-by: Kunchala Hema Sai Venkat Chandra Kumar <kumarchanduk@gmail.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a new "Brev" troubleshooting section to the docs describing remediation steps for OpenClaw on Brev: blocked skills, permission errors when setting config, restoring an unreachable dashboard, and fixes for non-functional skill install buttons. ChangesBrev Troubleshooting Guide
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/get-started/troubleshoot-brev.md (2)
39-42: ⚡ Quick winConvert passive phrasing to active voice.
Examples include “are blocked,” “cannot be enabled,” and “is owned… and mounted…”. Rewriting these in active voice will align with doc style.
As per coding guidelines, “Active voice required. Flag passive constructions.”
Also applies to: 63-63, 87-88
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/get-started/troubleshoot-brev.md` around lines 39 - 42, Rewrite the passive sentences in the shown lines into active voice: change "are blocked" to an active subject (e.g., "The sandbox blocks skills that require macOS-only binaries such as `memo`, `remindctl`, or `grizzly`"), change "are blocked" for CLI and credential lines similarly (e.g., "The sandbox blocks skills that require additional CLIs..." and "Skills that require API credentials remain blocked until you configure those credentials"), and apply the same active-voice rewrite to the other flagged locations (lines noted as 63 and 87-88) so each sentence uses a clear subject performing the action rather than passive constructions like "cannot be enabled" or "is owned… and mounted…".
32-43: ⚡ Quick winReplace bold pseudo-headings with real section structure (LLM pattern detected).
The repeated
**Symptom.**,**Cause.**,**Fix.**, and**Workaround.**pattern reads like generated formatting and is better expressed as H3 subheadings under each H2.As per coding guidelines, unnecessary bold on routine instructions should be flagged (“LLM pattern detected”), and sections should use H2/H3 structure.
Also applies to: 79-90, 136-144, 160-168
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/get-started/troubleshoot-brev.md` around lines 32 - 43, Replace the bold pseudo-headings like "**Symptom.**", "**Cause.**", "**Fix.**", and "**Workaround.**" with proper Markdown heading structure: make the section title (e.g., "Troubleshooting Brev" or existing H2) an H2 and convert each pseudo-heading into an H3 (e.g., "### Symptom", "### Cause", "### Fix", "### Workaround"); remove unnecessary bolding on routine instructions and ensure consistency across the document (apply the same replacement for the other occurrences noted around lines 79-90, 136-144, and 160-168) so headings are semantic and not LLM-style bold fragments.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/get-started/troubleshoot-brev.md`:
- Line 99: The ordered list in the markdown (starting at the item "Copy the
config file to a writable location.") uses mixed numeric markers; update each
ordered-list marker for that entire list so every item uses "1." (normalize
markers to "1." per MD029) — apply the same change to the other listed locations
(the items at the equivalents of lines 107, 113, and 121) so the whole ordered
list(s) consistently use "1." for each entry.
- Around line 18-21: The SPDX header in the Markdown HTML comment block uses the
year range "2025-2026" but our repo requires the exact 2026 format string;
update the SPDX comment (the block containing SPDX-FileCopyrightText and
SPDX-License-Identifier) by replacing "2025-2026" with "2026" so the header
matches the required SPDX-FileCopyrightText format for Markdown files.
---
Nitpick comments:
In `@docs/get-started/troubleshoot-brev.md`:
- Around line 39-42: Rewrite the passive sentences in the shown lines into
active voice: change "are blocked" to an active subject (e.g., "The sandbox
blocks skills that require macOS-only binaries such as `memo`, `remindctl`, or
`grizzly`"), change "are blocked" for CLI and credential lines similarly (e.g.,
"The sandbox blocks skills that require additional CLIs..." and "Skills that
require API credentials remain blocked until you configure those credentials"),
and apply the same active-voice rewrite to the other flagged locations (lines
noted as 63 and 87-88) so each sentence uses a clear subject performing the
action rather than passive constructions like "cannot be enabled" or "is owned…
and mounted…".
- Around line 32-43: Replace the bold pseudo-headings like "**Symptom.**",
"**Cause.**", "**Fix.**", and "**Workaround.**" with proper Markdown heading
structure: make the section title (e.g., "Troubleshooting Brev" or existing H2)
an H2 and convert each pseudo-heading into an H3 (e.g., "### Symptom", "###
Cause", "### Fix", "### Workaround"); remove unnecessary bolding on routine
instructions and ensure consistency across the document (apply the same
replacement for the other occurrences noted around lines 79-90, 136-144, and
160-168) so headings are semantic and not LLM-style bold fragments.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 33983fbd-e760-4d7d-9637-b66b39a5f9ff
📒 Files selected for processing (1)
docs/get-started/troubleshoot-brev.md
|
Thank you for the contribution. Please migrate the content to the existing troubleshooting page. And please make sure the content you have created follows the existing formatting in the central troubleshooting page. |
|
Thank you for the guidance, @miyoungc. I will migrate the content to the existing troubleshooting page and match the existing formatting. Will push the update shortly. |
Signed-off-by: Kunchala Hema Sai Venkat Chandra Kumar <kumarchanduk@gmail.com>
Content migrated to docs/reference/troubleshooting.md Brev section. Signed-off-by: Kunchala Hema Sai Venkat Chandra Kumar <kumarchanduk@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/reference/troubleshooting.md (1)
903-911: ⚡ Quick winRewrite these lines to active voice and direct second-person guidance.
This block uses passive constructions (“Skills are blocked…”, “can be enabled/unblocked…”). Prefer direct active phrasing with “you” to match docs voice rules.
As per coding guidelines, “Active voice required.” and “Second person (‘you’) when addressing the reader.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reference/troubleshooting.md` around lines 903 - 911, Rewrite the paragraph to use active voice and address the reader as "you": replace passive sentences like "Skills are blocked for one of three reasons" with "A skill is blocked for one of three reasons" or "You may find a skill blocked for one of three reasons," and convert "Skills that require macOS-only binaries cannot be enabled on Brev" to "You cannot enable skills that require macOS-only binaries on Brev." Also change "can be unblocked by installing" to "You can unblock skills that require Linux-compatible CLIs by installing the required binary on the Brev host." Ensure examples remain (memo, remindctl, grizzly, gh, Notion API key, Discord bot token) and keep the three bullet causes but phrased directly to the reader.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/reference/troubleshooting.md`:
- Around line 955-957: Update the CLI example to use the correct command order:
replace the incorrect "nemoclaw <name> onboard" instance with "nemoclaw onboard"
in the docs so the onboarding example matches the actual CLI flow and will not
confuse readers; ensure any surrounding text or examples that reference the
wrong form are updated to the canonical "nemoclaw onboard" usage.
- Line 959: The sentence "This restores the gateway connection without deleting
the sandbox or losing workspace files." makes an absolute guarantee; reword it
to remove the hard safety claim by qualifying the outcome and noting possible
exceptions (e.g., onboarding may recreate resources depending on state or
prompts). Replace the sentence with a cautious alternative such as: "This
typically restores the gateway connection and does not usually delete the
sandbox or cause workspace file loss, but depending on system state or
onboarding prompts resources may be recreated." Ensure the new text replaces the
original sentence in the troubleshooting entry.
---
Nitpick comments:
In `@docs/reference/troubleshooting.md`:
- Around line 903-911: Rewrite the paragraph to use active voice and address the
reader as "you": replace passive sentences like "Skills are blocked for one of
three reasons" with "A skill is blocked for one of three reasons" or "You may
find a skill blocked for one of three reasons," and convert "Skills that require
macOS-only binaries cannot be enabled on Brev" to "You cannot enable skills that
require macOS-only binaries on Brev." Also change "can be unblocked by
installing" to "You can unblock skills that require Linux-compatible CLIs by
installing the required binary on the Brev host." Ensure examples remain (memo,
remindctl, grizzly, gh, Notion API key, Discord bot token) and keep the three
bullet causes but phrased directly to the reader.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 7d95d754-c273-45a4-be18-076fda66e830
📒 Files selected for processing (1)
docs/reference/troubleshooting.md
|
@miyoungc Done. I have migrated the content to the existing troubleshooting page at docs/reference/troubleshooting.md as a new Brev section. The standalone file has been removed. Please let me know if any further changes are needed. |
miyoungc
left a comment
miyoungc
left a comment
There was a problem hiding this comment.
I checked the Brev troubleshooting additions against the current NemoClaw CLI and sandbox docs. A few items below need accuracy fixes before this merges.
Signed-off-by: Kunchala Hema Sai Venkat Chandra Kumar <kumarchanduk@gmail.com>
There was a problem hiding this comment.
🧹 Nitpick comments (2)
docs/reference/troubleshooting.md (2)
1044-1044: ⚡ Quick winUse active voice.
"has been run" is passive. Rewrite to active voice.
Suggested revision:
-When `nemoclaw <name> shields up` has been run, `openclaw.json` is owned by root and mounted read-only inside the sandbox. +After you run `nemoclaw <name> shields up`, `openclaw.json` becomes owned by root and is mounted read-only inside the sandbox.As per coding guidelines: "Active voice required. Flag passive constructions."
🤖 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 `@docs/reference/troubleshooting.md` at line 1044, Rewrite the passive sentence into active voice: replace "When `nemoclaw <name> shields up` has been run, `openclaw.json` is owned by root and mounted read-only inside the sandbox." with an active formulation, e.g. "When you run `nemoclaw <name> shields up`, the sandbox mounts `openclaw.json` as a read-only file owned by root." Use the command `nemoclaw <name> shields up`, the filename `openclaw.json`, and "sandbox" to locate the sentence to update.
1051-1051: ⚡ Quick winUse active voice.
"is writable by the sandbox user" is passive. Rewrite to active voice.
Suggested revision:
-In the default sandbox state (before `shields up`), `openclaw.json` is writable by the sandbox user. +In the default sandbox state (before `shields up`), the sandbox user can write to `openclaw.json`.As per coding guidelines: "Active voice required. Flag passive constructions."
🤖 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 `@docs/reference/troubleshooting.md` at line 1051, Rewrite the passive sentence "In the default sandbox state (before `shields up`), `openclaw.json` is writable by the sandbox user." into active voice so the subject performs the action; for example, make it "In the default sandbox state (before `shields up`), the sandbox user can write to `openclaw.json`." Ensure `openclaw.json` and the parenthetical `shields up` remain intact.
🤖 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.
Nitpick comments:
In `@docs/reference/troubleshooting.md`:
- Line 1044: Rewrite the passive sentence into active voice: replace "When
`nemoclaw <name> shields up` has been run, `openclaw.json` is owned by root and
mounted read-only inside the sandbox." with an active formulation, e.g. "When
you run `nemoclaw <name> shields up`, the sandbox mounts `openclaw.json` as a
read-only file owned by root." Use the command `nemoclaw <name> shields up`, the
filename `openclaw.json`, and "sandbox" to locate the sentence to update.
- Line 1051: Rewrite the passive sentence "In the default sandbox state (before
`shields up`), `openclaw.json` is writable by the sandbox user." into active
voice so the subject performs the action; for example, make it "In the default
sandbox state (before `shields up`), the sandbox user can write to
`openclaw.json`." Ensure `openclaw.json` and the parenthetical `shields up`
remain intact.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 11c2fca9-bdbe-4f63-b6ec-c14b6b310110
📒 Files selected for processing (1)
docs/reference/troubleshooting.md
miyoungc
left a comment
miyoungc
left a comment
There was a problem hiding this comment.
Accuracy note on the Brev troubleshooting fixes.
miyoungc
changed the title
miyoungc
left a comment
miyoungc
left a comment
There was a problem hiding this comment.
Lint fix suggestion for markdownlint MD031.
|
Thank you for the thorough review and all the direct fixes, @miyoungc . The PR looks ready from my side. Please let me know if there is anything else needed to get the workflows approved for merge. |
3 participants
docs(get-started): add Brev troubleshooting guide
Summary
Adds a troubleshooting guide for common issues when running NemoClaw
on Brev. Covers blocked skills, read-only openclaw.json, dashboard
connectivity loss, and skill install failures. Based on real first-hand
experience deploying NemoClaw via the Brev web UI on April 29, 2026.
Related Issue
None
Changes
Type of Change
Verification
npx prek run --all-filespassesnpm testpassesmake docsbuilds without warnings (doc changes only)AI Disclosure
Signed-off-by: Kunchala Hema Sai Venkat Chandra Kumar kumarchanduk@gmail.com
Summary by CodeRabbit