How to Troubleshoot and Debug Provider Fetch Failures in CodexBar

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:

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:

codexbar diagnose --json

The command outputs JSON similar to:

{
  "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 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.

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

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 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, this strategy fails when the refresh token is expired or invalid. Verify credential storage in Sources/CodexBarCore/KeychainAccessGate.swift.

CLI Import Strategy

Defined in 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) fails due to cookie import errors or HTML layout changes. APITokenFetchStrategy (in 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.

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 supports forced modes.

Test individual strategies:

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. Run these to verify the fetch logic in isolation:

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:

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 and its implementations (OAuth, CLI, Web, or API token) for implementation-specific errors.
• Verify Keychain access via 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) 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 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 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 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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}