Troubleshooting
Error messages and connection problems, with the fix.
This section is for the moment something does not work: an error message in the terminal, an agent that cannot see its project, a pull request that fails the check, test results that never reach the criteria. Each article starts from the symptom, explains why it happens and ends with the fix.
Most connection problems come down to identity. A token was revoked or expired, a sign-in was never completed, or the person behind the connection lost access to the project. The first articles cover those, including what 401 invalid_token means and why Claude Code may show the server as failed.
Other problems are about rules working as intended: a proposal refused because the connection is read-only, an action refused for lack of permission, a pull request that cites no record. The refusal usually says which permission is missing and who holds it.
If your problem is not an error but an agent doing the wrong thing, look in “When things go wrong” instead; if you still cannot find it, write to us with the project, the time and what you saw.
Articles in Troubleshooting
- Troubleshooting401 invalid_tokenCorpole refused the agent's credentials. The token is revoked or expired, the project is not active, or its owner can no longer read the project.
- TroubleshootingClaude Code shows corpole as failedThe MCP server is listed but not connected. Usually Claude Code has neither a token nor an OAuth sign-in for it.
- TroubleshootingThe agent's proposal was refusedpropose_record and the other write tools need the propose permission. A read-only connection can read everything its owner can, but cannot propose.
- TroubleshootingMy agent ignores the requirementsThe agent writes code without reading Corpole, or follows a file in the repository instead. Most often the repository does not tell it that Corpole comes first.
- TroubleshootingMy agent sees the wrong project, or noneEvery connection belongs to exactly one project. The agent sees the project its token was created in, or the one chosen on the OAuth consent screen.
- Troubleshooting"You don't have permission"Corpole refused an action because you, or the person your agent acts for, lack the permission. The message names the permission, who holds it and where it is done.
- TroubleshootingThe GitHub check fails on my pull requestThe Corpole check wants every pull request to cite existing, non-retired record or work item codes.
- TroubleshootingTest results don't show up on the criteriaA criterion follows the test cases linked to it. If results do not arrive, the test is not linked, or its automation reference does not match what CI reports.