Reference
Troubleshooting
Find the message or symptom you’re seeing, then follow the fix. Messages are quoted as Groundrule shows them; … stands for a name, address, or number that changes.
Two commands help with most CLI problems:
npx @groundrule/cli doctor # checks Node.js, git, the configuration, the connection, and the agent filesnpx @groundrule/cli whoami # shows which workspaces this computer is signed in toCLI exit codes: 0 means success, 1 means the check failed (or sync --check found stale files), and 2 means a usage or setup problem, such as not being signed in.
Signing in
Section titled “Signing in”| Symptom or message | Cause | Fix |
|---|---|---|
| “That email and password don’t match.” | The password is wrong, or the account has no password (it was created with GitHub or an email link). | Use Email me a sign-in link instead, or Forgot password?. |
| “Confirm your email first. We’ve sent you a new link.” | You haven’t confirmed your email address. | Open the newest email from Groundrule and choose Confirm and continue. |
| No confirmation or sign-in email | It’s in spam, or the address was mistyped. | Search your mail for “Groundrule”; choose Send it again, or Use a different email. |
| “Couldn’t send another link yet. Wait a few minutes and try again.” | Three links were sent to this address in the last hour (15 minutes for sign-in links). | Wait, then try again. Use the newest email you already have. |
| Link expired (“This … link doesn’t work.”) | The link was used, replaced by a newer one, or is too old: 24 hours for confirmation, 15 minutes for sign-in, 30 minutes for reset. | Choose the button on the page to get a new link. |
| An email says you already have an account | You signed up with an address that already has one. | Sign in instead, or use Forgot password?. |
| “Too many attempts. Wait a few minutes and try again.” | Too many attempts for this email or from your network. Accounts never lock. | Wait 15 minutes. See Limits. |
| “GitHub sign-in didn’t complete. Please try again.” | The approval on GitHub was cancelled or took over 10 minutes. | Start again with Continue with GitHub. |
| “Your GitHub account has no verified primary email. …” | Groundrule identifies GitHub users by their verified primary email. | Verify your primary email on GitHub, then try again. |
| Continue with GitHub isn’t shown | GitHub sign-in isn’t enabled on this deployment. | Use your email and password, or an email link. |
| You land in another workspace than expected | You belong to several; Groundrule opens the first alphabetically. | Switch in the account menu at the bottom of the sidebar. |
| A workspace URL sends you back to your own workspace | You aren’t a member of it. | Ask one of its admins to invite you. |
| “This invitation can only be accepted by …” | You’re signed in with a different email than the one invited. | Choose Sign out and continue as the invited address. |
| “This invitation has expired.” / “… was withdrawn.” / “… was already used.” | Invitations last 7 days and work once; an admin may have revoked it. | Ask an admin for a new invitation. |
More: Sign in and your account.
CLI login
Section titled “CLI login”| Symptom or message | Cause | Fix |
|---|---|---|
“The code expired. Run groundrule login again.” |
The code wasn’t approved within 10 minutes. | Run npx @groundrule/cli login again and approve promptly. |
| “The sign-in was declined in the browser. Nothing was saved.” | Someone chose Deny on the approval page. | Run login again and choose Approve. |
Approval page: “This code isn’t valid. It may have expired; run groundrule login again.” |
The code is wrong, expired, or already used. | Compare it with your terminal, or run login again. |
| Approval page: “You’re not in a workspace yet.” | Your account has no workspace. | Choose Create one, then run login again. |
| The browser doesn’t open | No browser on this machine, such as over SSH. | Open the Approve it at URL from the terminal on any device where you’re signed in. |
| “Refusing to send credentials to …: use https (plain http is only allowed for localhost).” | --url or GROUNDRULE_URL uses http://. |
Use https://app.groundrule.dev. |
| “Couldn’t reach Groundrule at … Check your connection or GROUNDRULE_URL.” | No network, a proxy, or a wrong GROUNDRULE_URL. |
Check your connection; unset GROUNDRULE_URL or correct it. An empty value counts as unset. |
| “This repository uses …. Run login again and approve it for ….” | You approved a different workspace than the one in .groundrule/config.yaml. |
Run login again and pick the right workspace on the approval page. |
whoami says “Not signed in. Run groundrule login.” |
This computer has no saved login, or the folder’s configuration names another server. | Run login. Run whoami outside the repository to list every saved login with its server. |
More: CLI quickstart, API tokens.
Connecting a repository and sync
Section titled “Connecting a repository and sync”| Symptom or message | Cause | Fix |
|---|---|---|
“No Groundrule config found. Run groundrule init to create one.” |
The repository has no .groundrule/config.yaml. |
Run npx @groundrule/cli init --org acme-payments. |
| “✕ .groundrule/config.yaml already exists. Use –force to overwrite it.” | init won’t replace an existing configuration. |
Edit the file, or run init --force to start over. |
| “✕ “…” isn’t an organization URL name. Use the part after groundrule.dev/, e.g. acme.” | --org was given the workspace’s display name or a full URL. |
Use the URL name, such as acme-payments. Copy it from Settings → Workspace. |
“Not signed in to … on …. Run groundrule login (or set GROUNDRULE_TOKEN in CI).” |
No saved login for this workspace, and no GROUNDRULE_TOKEN. |
Run login locally; set the secret in CI. |
“Your sign-in to … has expired or was revoked. Run groundrule login again.” |
The 90-day login token expired or was revoked. | Run login again. |
| “GROUNDRULE_TOKEN isn’t valid. It may have expired or been revoked; create a new one in Groundrule → Settings → API tokens.” | The CI token expired, was revoked, or its owner left the workspace. | Create a new token and update the secret. |
| “This token is for …, but this repository uses ….” | The token belongs to another workspace. | Use a token from the workspace named in .groundrule/config.yaml. |
| “… isn’t registered in …, so the organization’s rules apply. Add it under Teams → Repositories to use its team’s settings.” | A warning: the repository isn’t registered, so team settings can’t apply. | An admin or platform admin adds it under Teams → Repositories. Ignore it if you have no teams. |
“Ignored because platform is set: your organization’s rulebook decides the packs.” |
The configuration lists extends packs and is also connected to a workspace. |
Remove extends; turn packs on in the dashboard instead. |
| “… comes from the platform; change it in Groundrule (for this repository or its team), not in config.” | A local overrides entry targets a platform rule. |
Change the rule in its rollout panel in the dashboard. |
| “… is also an organization rule; the organization’s version applies. Give this one a new ID.” | A local standard uses the same ID as one of your workspace’s standards. | Rename the local standard’s ID. |
| “Skipped … from the platform: it doesn’t match this CLI’s spec (upgrade @groundrule/cli).” | Your CLI is older than the rulebook’s format. | Use the latest version: npx @groundrule/cli@latest. |
A rule you recently published isn’t in AGENTS.md |
It’s a draft, it’s at Observe, or it’s turned off. sync writes only rules at Teach, Advise, and Enforce. |
Publish it, or move it to Teach. Then run sync again. |
sync --check fails: “Agent instructions are out of date” |
The rulebook changed since the agent files were last written. | Run npx @groundrule/cli sync and commit the result. |
More: Agent instruction files, Configuration.
| Symptom or message | Cause | Fix |
|---|---|---|
| “Cannot compare against “…”. Fetch it first (e.g. git fetch origin main).” | The base branch isn’t in the local clone. CI often clones only the latest commit. | Run git fetch origin main first, or clone with full history (in GitHub Actions, fetch-depth: 0 on actions/checkout). |
| The check passes, but you expected a finding | The rule isn’t at Enforce, its severity is below failOn, the finding is on a line you didn’t change, or an exception covers it. |
Run npx @groundrule/cli check --all --verbose and npx @groundrule/cli explain <ID>. |
| The check fails on code you didn’t touch | scope: all, or legacy: enforce, in .groundrule/config.yaml. |
Use scope: changed-lines and legacy: report to fail only on new violations. |
| “Semgrep is not installed. …” | A rule uses a Semgrep check. | Install Semgrep (brew install semgrep or pipx install semgrep), or accept that those rules are skipped. |
| “Configuration has errors (see above)” | .groundrule/config.yaml or a local standard is invalid. |
Fix the lines named above it. npx @groundrule/cli doctor lists them. |
| “Invalid escape sequence” when saving a check | A regular expression in double quotes in YAML, such as "\w+". |
Put regex patterns in single quotes: '\w+'. |
More: Check your changes, Run Groundrule in CI.
Scan uploads
Section titled “Scan uploads”| Symptom or message | Cause | Fix |
|---|---|---|
| “✕ Upload failed: this token can’t upload scans. …” | The token doesn’t have Upload scans. | Run login again, or create a token with Upload scans in Settings → API tokens. |
“✕ Not signed in to … on …. Run groundrule login (or set GROUNDRULE_TOKEN in CI).” |
No login for this workspace. | Run login, or set GROUNDRULE_TOKEN. |
| “! Scanning the catalog only: …” | The scan couldn’t fetch your workspace’s own rules, so it tested catalog rules only. | Check the reason after the colon; usually the token or the network. |
| “Too many scans uploaded. Try again later.” | More than 60 uploads an hour from one token, or 1,000 a day in the workspace. | Scan less often, for example nightly. |
| The repository shows Not registered | Scans recorded it, but it isn’t under Teams → Repositories. | Register it there to apply team settings. |
| The dashboard’s Connect the CLI step stays undone | No API token has been used and no scan uploaded yet. | Run sync or scan --upload from a signed-in repository. |
More: Scan repositories.
Inbox and AI
Section titled “Inbox and AI”| Symptom or message | Cause | Fix |
|---|---|---|
| No Accept or Reject buttons | Your role can’t decide on proposals. Ownership proposals need an admin or platform admin. | Ask an admin to change your role, or to decide. See Roles and permissions. |
| “Your role (…) can’t …. Ask an admin.” | The action needs another role. | As above. |
| Describe a rule or Draft with AI is missing | AI is off for the workspace, or your role can’t author. | An admin turns AI on in Settings → AI. |
| “AI features are turned off for this workspace. An admin can turn them on in Settings → AI.” | AI is off. | An admin turns it on. |
| “This workspace has used $… of its $… monthly AI budget. An admin can raise it in Settings → AI.” | The monthly budget is spent, or the request’s estimate would exceed it. | An admin raises the budget, or wait for the 1st of the month (UTC). |
| “This workspace requires zero data retention, which this deployment doesn’t have yet. Nothing was sent.” | Zero retention is selected but not available. | An admin switches to Standard retention or turns AI off. |
| “The AI declined this request. Try rewording, or do it by hand.” | The model refused. | Reword the input, or write the standard yourself. |
| “The AI’s answer was cut off or unreadable. Try a shorter input.” | The input was too long for one answer. | Shorten it, or split it. |
| “The AI’s answer didn’t pass validation after one repair.” | The model’s answer wasn’t a valid standard. | Try again, or write it by hand. Nothing was saved. |
| “The AI provider failed. Try again.” | The model provider had an error or didn’t respond. | Try again shortly. |
| “Too many AI requests. Wait a few minutes and try again.” | 60 AI requests an hour per person, or 300 per workspace. | Wait. |
| “Say the rule in a sentence.” | A proposed rule is under 10 characters. | Write the rule as a full sentence. |
“This sign-in can’t propose rules yet. Run groundrule login again to refresh it.” |
The token in use doesn’t have Propose rules. | Run login again. In CI, use a token created with Propose rules. |
More: The review inbox, AI settings and usage.
Imports
Section titled “Imports”| Symptom or message | Cause | Fix |
|---|---|---|
| “This file type isn’t supported. Use PDF, DOCX, Markdown, or text.” | Another format, such as .doc, .pages, or HTML. |
Export it as PDF, DOCX, or Markdown. |
| “This file isn’t valid UTF-8 text. …” | A text file in another encoding. | Save it as UTF-8. |
| “Only .docx files are supported from zip-based formats.” | A zip file, or an .xlsx or .pptx. |
Export the content as DOCX or PDF. |
| “This DOCX file is damaged.” / “… couldn’t be read.” | The file is corrupt. | Open and re-save it in Word, or export as PDF. |
| “Files can be up to 10 MB.” | The file is larger than 10 MB. | Split it, or paste the relevant text. |
| “This PDF has … pages; the limit is 200. …” | The PDF is longer than 200 pages. | Split it. |
| “This document has more than 1,500,000 characters of text. …” / “… too many paragraphs. …” | The document is too large. | Split it. |
| “This document is empty.” | The file has no content. | Check you chose the right file. |
| “No text found in this PDF. Scanned PDFs need OCR first.” / “No text found in this document.” | The PDF is scanned images, or the document has no text. | Run OCR on the PDF first, or paste the text. |
| “Reading this document is estimated at $…, but only $… of this month’s AI budget is left. …” | The estimate exceeds the remaining budget. Nothing was sent. | An admin raises the budget, or import a smaller part. |
| Citations point only to “page 1”, “page 2” | The PDF has no heading styles, so each page is one passage. | Import a DOCX or Markdown version to cite headings. |
| An import disappeared before you started it | Imports you don’t start are discarded after 24 hours. | Import it again. |
| “Interrupted. Import the document again.” | The import was interrupted while reading. | Import it again. |
| “There are no imported agent-file instructions left to refine.” | Every instruction from agent files was already refined or decided. | Nothing to do. |
| “Connect GitHub in Settings → Connections first.” | PR review import needs the GitHub App. | An admin installs it. See Connections. |
| “No review comments from people in the last … days in those repositories.” | No human review comments in that period; bot comments are ignored. | Choose a longer period or other repositories. |
| “Choose repositories the GitHub App can read.” | A chosen repository isn’t covered by the installation. | Add it with Change repositories on GitHub. |
More: Import documents, Rules from pull-request reviews.
Connections
Section titled “Connections”| Symptom or message | Cause | Fix |
|---|---|---|
| Not set up on this deployment | The Groundrule service you use isn’t registered with that app. | Ask whoever runs it. |
| No Connect button | Only admins and platform admins connect apps. | Ask one of them. |
| “Connections are managed by admins and used by standard owners. …” | Your role can’t use connections. | Ask an admin to import for you, or to change your role. |
| “Access wasn’t granted, so nothing was connected.” | The consent screen was declined. | Connect again and approve. |
| “The connection didn’t complete (the request expired or came from elsewhere). Try again.” | The approval took too long, or started in another browser. | Start again in the same browser. |
| Needs reconnecting, or “… needs to be reconnected.” | The app no longer accepts Groundrule’s access. | Connect the same account again. |
| “No Confluence site was shared with Groundrule.” | No site was chosen during approval. | Connect again and choose a site. |
| “That isn’t a Notion page.” / “That isn’t a Confluence page.” | The link or result isn’t a page. | Use a page link. |
| “… couldn’t find this document.” | It was deleted, or isn’t shared with the integration. | In Notion, share the page with the Groundrule integration; in Google Docs, check you can open it. |
| “This … page is too long to import.” | The page exceeds the import size. | Split the page, or paste the relevant part. |
| “The connected app didn’t respond. Try again shortly.” | The app had an outage. | Try again later. |
| “That GitHub installation is already connected to another Groundrule workspace.” | One installation serves one workspace. | Disconnect it there first. |
| “That GitHub installation is suspended. …” | It’s suspended on GitHub. | Unsuspend it on GitHub, then connect again. |
More: Connections.
Still stuck?
Section titled “Still stuck?”Run npx @groundrule/cli doctor and keep its output. Then email hello@groundrule.dev with what you ran, what you expected, and the message you saw. Never include a token.