docs / troubleshooting
When something looks wrong
Most of the behaviours that seem surprising at first are deliberate. For each case below, you'll find what you're seeing, why it happens, and what — if anything — you need to do.
The toolbar doesn't appear
- ·The domain isn't authorized yetThe extension runs only where you have allowed it, github.com included: a fresh install is active nowhere until you grant a first domain from its options page. For a domain the extension doesn't already know — a self-hosted instance, an internal host — you also need to specify which platform it is running so the extension can select the correct adapter.
- ·One of the extension's selectors found nothingWhen the element a rule looks for isn't there, the extension disables the affected area rather than risk interacting with the wrong one. That can mean the platform changed its markup — or simply that the element is legitimately absent, like the merge button on a closed pull request. The options page's “Status” section keeps a log of the last fifty occurrences, containing only the rule name and timestamp — never review content.
- ·The mode is
offThe organization or repository configuration can disable the extension entirely.
“Configuration unread” banner
The extension could not retrieve .conventional-comments.json. It continues to assist, but because it cannot determine the repository's rules, it never blocks a comment from being submitted. That behaviour is intentional: a user should not be prevented from working because of a rule the extension itself could not read.
A repository with no .conventional-comments.json file at all is not an error or degraded state. In that case, the product defaults apply and no banner is shown. The banner only appears when there is configuration to retrieve but the extension cannot read it. For a public repository — or a private repository while you're authenticated — you should not normally see it. If you're signed out and the repository is private, the banner is accurately reporting that the configuration cannot be accessed.
/rebase is being rejected
This is expected: toolCommands is empty by default, so nothing is exempted until the repository declares it.
"toolCommands": ["/*", "@dependabot", "@renovate"]
"/*" recognizes every slash command as a tool command. Bot handles are declared individually and matched against the complete first token. For example, @codex review is recognized as a command, while @codexplains why is not.
A bot's comments fail the check
Add the bot's platform login to exemptUsers. Matching is case-insensitive and uses the platform login, not the display name.
Platform-generated entries such as timeline events, branch updates, and system notifications are exempt automatically and do not need to be listed. An approval with no review text at all is also always exempt. Otherwise, simply approving a pull request without writing a comment would produce a validation failure — one the author of the pull request could not fix, because they cannot edit somebody else's review.
A blocking point can't be resolved
A blocking thread can be resolved only by:
- the author of the blocking comment, or
- a member of the group configured for resolution overrides.
If nobody can resolve it, the designated group is probably empty. That group is a prerequisite for enforce precisely to prevent a blocking thread from becoming impossible to resolve.
The other option is a decision reply explaining why the point will not be addressed. A decision must contain at least twenty characters of justification. The explanation is recorded directly in the thread, so the override is always explicit and visible.