# How to Troubleshoot and Debug Provider Fetch Failures in CodexBar

> Troubleshoot provider fetch failures in CodexBar by enabling debug logging, running diagnose, and inspecting provider implementations. Fix credential issues and network problems fast.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-08

---

**To troubleshoot provider fetch failures in CodexBar, enable debug logging with `CODexBarLogLevel=debug`, run `codexbar diagnose --json` to identify the error category, and inspect the specific `ProviderFetchStrategy` implementation in the provider's descriptor file to verify credentials, network endpoints, and Keychain access.**

CodexBar, developed by steipete, aggregates AI usage data from multiple providers through a modular fetch pipeline orchestrated by `ProviderFetchPlan` and `ProviderDiagnostic` objects. When a provider fails to return usage statistics, understanding the relationship between the descriptor configuration, fetch strategies, and error classification is essential to troubleshoot and debug provider fetch failures in CodexBar effectively.

## Enable Structured Debug Logging

CodexBar uses a structured logger defined in `Sources/CodexBar/UsageStore+Logging.swift` that emits detailed fetch outcomes and diagnostic payloads. Increase the log level to `debug` to see every stage of the fetch pipeline.

Set the environment variable before launching the app:

```bash
export CODexBarLogLevel=debug
open -a CodexBar

```

This outputs detailed messages including strategy selection, network request URLs, and raw response parsing, allowing you to pinpoint exactly where the fetch pipeline encounters an error.

## Run the Built-In Diagnose Command

The `codexbar` CLI includes a `diagnose` sub-command that executes a full fetch for every enabled provider and surfaces structured `ProviderDiagnostic` objects. This is the fastest way to classify a failure.

Execute the diagnostic tool from your terminal:

```bash
codexbar diagnose --json

```

The command outputs JSON similar to:

```json
{
  "provider": "claude",
  "outcome": "failure",
  "errorCategory": "auth",
  "message": "OAuth token expired"
}

```

According to the steipete/CodexBar source code, this command is implemented in [`Sources/CodexBarCLI/CLIDiagnoseCommand.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIDiagnoseCommand.swift) and follows the exact same execution path as the GUI, ensuring consistent results between the CLI and the application interface.

## Inspect the Provider Descriptor Configuration

Each provider defines its fetch behavior in a `ProviderDescriptor` located at `Sources/CodexBarCore/Providers/<Name>/<Name>ProviderDescriptor.swift`. For example, the Claude provider is defined in [`Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift).

The descriptor specifies the `ProviderFetchPlan` which determines the order of strategies via `sourceModes`:

```swift
public static let descriptor = ProviderDescriptor(
    id: .claude,
    metadata: .make(...),
    fetchPlan: ProviderFetchPlan(
        sourceModes: [.auto, .cli, .web],
        pipeline: ProviderFetchPipeline(...)
    )
)

```

When debugging, verify three critical elements:

- **sourceModes**: The strategy precedence. If `.cli` appears before `.web`, a missing CLI binary causes an early failure before attempting web-based authentication.
- **pipeline**: The concrete `ProviderFetchStrategy` implementations available (e.g., `ClaudeOAuthFetchStrategy`).
- **metadata**: Dashboard URLs and endpoint configurations. Misconfigured URLs in `metadata.dashboardURL` or `fetchPlan.baseURL` cause network errors that surface as fetch failures.

## Analyze Fetch Strategy Execution

The `ProviderFetchPlan.fetchOutcome(context:provider:)` method in [`Sources/CodexBarCore/Providers/ProviderFetchPlan.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/ProviderFetchPlan.swift) resolves the pipeline and executes strategies in order. Understanding the specific strategy that fails helps isolate the root cause.

### OAuth Authentication Strategy

Implemented in provider-specific files like [`ClaudeOAuthFetchStrategy.swift`](https://github.com/steipete/CodexBar/blob/main/ClaudeOAuthFetchStrategy.swift), this strategy fails when the refresh token is expired or invalid. Verify credential storage in [`Sources/CodexBarCore/KeychainAccessGate.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/KeychainAccessGate.swift).

### CLI Import Strategy

Defined in [`Sources/CodexBarCore/Providers/CLIImportFetchStrategy.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/CLIImportFetchStrategy.swift), this fails when the provider's CLI binary is missing from the system `PATH` or returns unexpected output.

### Web and API Token Strategies

`WebFetchStrategy` (in [`Sources/CodexBarCore/Providers/WebFetchStrategy.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/WebFetchStrategy.swift)) fails due to cookie import errors or HTML layout changes. `APITokenFetchStrategy` (in [`Sources/CodexBarCore/Providers/APITokenFetchStrategy.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/APITokenFetchStrategy.swift)) fails when the API key is absent in the macOS Keychain.

To debug deeply, temporarily insert `log.debug` statements inside the strategy's `fetch` method to inspect request headers and raw responses before the error is mapped.

## Verify Credentials and Keychain Access

Authentication failures often originate in the macOS Keychain. CodexBar stores sensitive tokens via `KeychainAccessGate` in [`Sources/CodexBarCore/KeychainAccessGate.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/KeychainAccessGate.swift).

If the diagnostic output shows `errorCategory: "auth"`:

1. Open **Keychain Access** and search for the provider's service name (e.g., `ClaudeOAuthToken`).
2. Verify the entry exists and is not locked.
3. If the entry is corrupted, delete it and allow CodexBar to re-authenticate via the OAuth flow.

Ensure CodexBar has the necessary entitlements to access the Keychain, as permission denials manifest as silent authentication failures.

## Force Specific Fetch Modes for Isolation

When `.auto` mode selects a failing strategy, bypass it to test specific implementations. The CLI command in [`Sources/CodexBarCLI/CLIUsageCommand.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIUsageCommand.swift) supports forced modes.

Test individual strategies:

```bash
codexbar fetch --provider claude --mode web   # Bypass OAuth/CLI

codexbar fetch --provider claude --mode cli   # Test CLI import only

codexbar fetch --provider claude --mode oauth # Test OAuth refresh only

```

If `--mode web` succeeds while `--mode cli` fails, the issue is isolated to the CLI binary or `CLIImportFetchStrategy` configuration rather than network connectivity or OAuth credentials.

## Validate with Unit Tests and Clear Cache

The repository includes provider-specific tests in `Tests/CodexBarTests/` such as [`ClaudeProviderRuntimeTests.swift`](https://github.com/steipete/CodexBar/blob/main/ClaudeProviderRuntimeTests.swift). Run these to verify the fetch logic in isolation:

```bash
swift test --filter ClaudeProviderDescriptorTests

```

If tests pass but the UI fails, the discrepancy likely involves the runtime environment (Keychain permissions, cookies, or network proxies).

Stale cached data can also mask resolution attempts. Clear the `UsageStore` cache using the mechanism defined in `Sources/CodexBar/UsageStore+Timeout.swift`:

```swift
import CodexBar
try await UsageStore.shared.clearAll()

```

After clearing, trigger a fresh fetch to ensure you are debugging the current provider state rather than cached error conditions.

## Summary

To effectively troubleshoot and debug provider fetch failures in CodexBar:

- **Enable debug logging** by setting `CODexBarLogLevel=debug` to trace the fetch pipeline in `UsageStore+Logging.swift`.
- **Run `codexbar diagnose --json`** to obtain structured `ProviderDiagnostic` objects that classify failures as `network`, `auth`, or `parsing`.
- **Inspect the provider descriptor** in `Sources/CodexBarCore/Providers/<Name>/<Name>ProviderDescriptor.swift` to verify `sourceModes` ordering and pipeline configuration.
- **Check the specific strategy** in [`ProviderFetchPlan.swift`](https://github.com/steipete/CodexBar/blob/main/ProviderFetchPlan.swift) and its implementations (OAuth, CLI, Web, or API token) for implementation-specific errors.
- **Verify Keychain access** via [`KeychainAccessGate.swift`](https://github.com/steipete/CodexBar/blob/main/KeychainAccessGate.swift) when encountering authentication failures.
- **Force specific modes** using the CLI to isolate whether the issue affects all strategies or just one.
- **Run unit tests** and clear the `UsageStore` cache to eliminate environmental and stale data variables.

## Frequently Asked Questions

### How do I identify which fetch strategy is failing in CodexBar?

Run `codexbar diagnose --json` to see the `errorCategory` and associated message. Then examine the `sourceModes` array in the provider's descriptor file (e.g., [`ClaudeProviderDescriptor.swift`](https://github.com/steipete/CodexBar/blob/main/ClaudeProviderDescriptor.swift)) to see which strategy is active. Enable debug logging to see the specific strategy name printed when the fetch begins, as logged by `UsageStore+Logging.swift`.

### Why does my provider fetch succeed in unit tests but fail in the CodexBar app?

Unit tests in [`Tests/CodexBarTests/ClaudeProviderRuntimeTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/ClaudeProviderRuntimeTests.swift) run in a controlled environment without Keychain restrictions or network proxies. If tests pass but the app fails, check macOS Keychain permissions for `KeychainAccessGate`, verify that the CLI binary is in your user `PATH` (not just the test environment), and ensure the app has network entitlements. Also clear the `UsageStore` cache to rule out stale data masking the test conditions.

### What does the "auth" error category indicate in CodexBar diagnostics?

The `auth` category indicates that `ProviderFetchPlan` successfully selected a strategy but the authentication credentials were rejected. This typically occurs in `OAuthFetchStrategy` when the refresh token is expired, in `APITokenFetchStrategy` when the key is missing from the Keychain, or when [`KeychainAccessGate.swift`](https://github.com/steipete/CodexBar/blob/main/KeychainAccessGate.swift) cannot access the stored secret. Delete the existing Keychain entry for the provider and re-authenticate to resolve this.

### How can I test a specific fetch mode without using the GUI?

Use the CLI command implemented in [`Sources/CodexBarCLI/CLIUsageCommand.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIUsageCommand.swift) to force a specific mode. Execute `codexbar fetch --provider <name> --mode <web|cli|oauth|api>` to bypass the `.auto` selection logic. This allows you to determine if a failure is specific to one strategy (such as a missing CLI binary) or affects all fetch methods (indicating a network or configuration issue in the `ProviderDescriptor`).