fix(auth): classify permission_error as auth_permanent for profile fallback by Sid-Qin · Pull Request #31324 · openclaw/openclaw

Sid-Qin · 2026-03-02T05:40:34Z

Summary

Problem: When an OAuth auth profile returns HTTP 403 with permission_error (e.g. expired organization plan), the error is classified as generic auth instead of auth_permanent. The auth classification applies only a short cooldown, so the gateway keeps retrying the same broken profile indefinitely (20+ consecutive 403s observed).
Why it matters: Users lose access to their AI assistant for extended periods because profile rotation never triggers effectively. Manual intervention is required.
What changed: Added "permission_error" and "not allowed for this organization" to the authPermanent error patterns in ERROR_PATTERNS. This causes these errors to receive the longer disabledUntil backoff window (same treatment as revoked keys and billing errors), enabling proper rotation to the next healthy profile.
What did NOT change: The resolveFailoverReasonFromError function already returns auth for 403 status codes — this change makes it return auth_permanent when the error message contains permission_error. Regular 403s without permission_error still classify as auth.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes Auth profile fallback doesn't trigger on OAuth 403 permission_error (expired plan) #31306

User-visible / Behavior Changes

OAuth profiles that return permission_error are now placed into a longer disable window (exponential backoff) instead of a short cooldown.
The gateway automatically rotates to the next available auth profile when an OAuth profile's organization plan expires.
lastGood is cleared for the failing profile, preventing immediate re-selection.

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

Repro + Verification

Environment

OS: macOS / Linux
Runtime: Node.js 22+
Provider: Anthropic (OAuth auth profile)

Steps

Configure two auth profiles: anthropic:100 (token, valid) and anthropic:200 (OAuth, expired plan)
Let lastGood.anthropic point to anthropic:200
Send a message

Expected

Gateway tries :200, gets 403 permission_error, classifies as auth_permanent, disables profile, rotates to :100

Actual

Before: Gateway keeps retrying :200 with short cooldown, never effectively rotating
After: Gateway disables :200 with exponential backoff and rotates to :100

Evidence

Failing test/log before + passing after

Three new test cases in failover-error.test.ts:

403 permission_error returns auth_permanent (via status + message)
permission_error in error message string classifies as auth_permanent (via coercion)
"not allowed for this organization" classifies as auth_permanent

Human Verification (required)

Verified scenarios: permission_error with status 403; permission_error in error message string; "not allowed for this organization" variant; regular 403 without permission_error still returns auth
Edge cases checked: existing authPermanent patterns still work (revoked key, invalid_api_key, deactivated account)
What you did not verify: Live OAuth profile rotation with expired Anthropic plan

Compatibility / Migration

Backward compatible? Yes — only changes classification of a previously under-handled error
Config/env changes? No
Migration needed? No

Failure Recovery (if this breaks)

How to disable/revert: Remove "permission_error" and "not allowed for this organization" from authPermanent patterns in src/agents/pi-embedded-helpers/errors.ts
Files to restore: src/agents/pi-embedded-helpers/errors.ts

Risks and Mitigations

Risk: Transient permission errors (not plan-related) might get classified as permanent
- Mitigation: permission_error is a specific Anthropic error type for org-level permission issues, not transient API errors. Adding the more specific "not allowed for this organization" string narrows the match. Generic 403s still classify as auth (shorter cooldown).

…llback When an OAuth auth profile returns HTTP 403 with permission_error (e.g. expired plan), the error was not matched by the authPermanent patterns. This caused the profile to receive only a short cooldown instead of being disabled, so the gateway kept retrying the same broken profile indefinitely. Add "permission_error" and "not allowed for this organization" to the authPermanent error patterns so these errors trigger the longer billing/auth_permanent disable window and proper profile rotation. Closes openclaw#31306 Made-with: Cursor

greptile-apps · 2026-03-02T05:45:45Z

Greptile Summary

This PR fixes a critical failover bug where OAuth profiles returning HTTP 403 with permission_error (e.g., expired Anthropic organization plans) were classified as generic auth errors instead of auth_permanent, causing the gateway to retry broken profiles with only short cooldowns instead of rotating to healthy alternatives.

The fix adds two specific error patterns to the authPermanent classification in src/agents/pi-embedded-helpers/errors.ts:

"permission_error" - Anthropic's specific error type for org-level permission issues
"not allowed for this organization" - OAuth org restriction error text

These patterns now trigger the same exponential backoff as billing errors (via disabledUntil), enabling proper profile rotation.

Key changes:

Added 2 string patterns to ERROR_PATTERNS.authPermanent array
Added 3 comprehensive test cases covering both error classification paths
Maintained backward compatibility: regular 403s without these patterns still use short auth cooldown

Impact:

Prevents indefinite retries of broken OAuth profiles
Automatically rotates to healthy profiles when org plans expire
Applies appropriate backoff window for org-level permission failures

Confidence Score: 5/5

This PR is safe to merge with minimal risk
Score reflects a well-contained bug fix with comprehensive test coverage, clear backward compatibility, and straightforward rollback path. The change is minimal (2 patterns added), addresses a real production issue (20+ consecutive 403s), and has no security or breaking change implications.
No files require special attention

_{Last reviewed commit: 571d29f}

…llback (openclaw#31324) When an OAuth auth profile returns HTTP 403 with permission_error (e.g. expired plan), the error was not matched by the authPermanent patterns. This caused the profile to receive only a short cooldown instead of being disabled, so the gateway kept retrying the same broken profile indefinitely. Add "permission_error" and "not allowed for this organization" to the authPermanent error patterns so these errors trigger the longer billing/auth_permanent disable window and proper profile rotation. Closes openclaw#31306 Made-with: Cursor Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

…llback (openclaw#31324) When an OAuth auth profile returns HTTP 403 with permission_error (e.g. expired plan), the error was not matched by the authPermanent patterns. This caused the profile to receive only a short cooldown instead of being disabled, so the gateway kept retrying the same broken profile indefinitely. Add "permission_error" and "not allowed for this organization" to the authPermanent error patterns so these errors trigger the longer billing/auth_permanent disable window and proper profile rotation. Closes openclaw#31306 Made-with: Cursor Co-authored-by: Vincent Koc <vincentkoc@ieee.org> (cherry picked from commit 40e078a)

openclaw-barnacle bot added agents Agent runtime and tooling size: XS experienced-contributor labels Mar 2, 2026

vincentkoc added 2 commits March 1, 2026 22:24

Merge branch 'main' into fix/auth-profile-403-fallback-31306

bab481d

Merge branch 'main' into fix/auth-profile-403-fallback-31306

5207d33

vincentkoc merged commit 40e078a into openclaw:main Mar 2, 2026
5 checks passed

greptile-apps bot mentioned this pull request Mar 2, 2026

Docs: add changelog entry for auth permission error #31367

Merged

18 tasks

github-actions bot mentioned this pull request Mar 2, 2026

📡 Upstream Digest — 2026-03-02 06:46 UTC curtismercier/openclaw-mods#159

Open

Dingding-leo mentioned this pull request Mar 4, 2026

[Bug]: 401 missing authentication header #34830

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(auth): classify permission_error as auth_permanent for profile fallback#31324

fix(auth): classify permission_error as auth_permanent for profile fallback#31324
vincentkoc merged 3 commits intoopenclaw:mainfrom
Sid-Qin:fix/auth-profile-403-fallback-31306

Sid-Qin commented Mar 2, 2026 •

edited

Loading

Uh oh!

greptile-apps bot commented Mar 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Sid-Qin commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

greptile-apps bot commented Mar 2, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Sid-Qin commented Mar 2, 2026 •

edited

Loading