What causes "Official auth.json requires access_token" in jlcodes99/cockpit-tools?

Re-run the OAuth flow to repopulate tokens.access_token

Official auth.json requires access_token

Error message

Official auth.json requires access_token

What it means

toOfficialAuthJson throws this error when the account is not an API-key account and its tokens.access_token is missing or blank. Every official auth.json variant for non-API-key accounts (OAuth, personal access token) requires an access token.

Source

Thrown at src/utils/codexExportFormats.ts:547

      agent_identity: buildAgentIdentityCredentials(account),
      type: 'codex',
    };
  }

  if (isCodexApiKeyAccount(account)) {
    const apiKey = account.openai_api_key?.trim();
    if (!apiKey) {
      throw new Error('Official auth.json requires OPENAI_API_KEY for API Key accounts');
    }
    return {
      auth_mode: 'apikey',
      OPENAI_API_KEY: apiKey,
    };
  }

  const accessToken = account.tokens?.access_token?.trim() || '';
  if (!accessToken) {
    throw new Error('Official auth.json requires access_token');
  }

  if (isPersonalAccessTokenAccount(account)) {
    return {
      OPENAI_API_KEY: null,
      personal_access_token: accessToken,
      type: 'codex',
    };
  }

  return {
    OPENAI_API_KEY: null,
    tokens: {
      id_token: account.tokens?.id_token || '',
      access_token: accessToken,
      refresh_token: account.tokens?.refresh_token?.trim() || '',
      account_id: resolveAccountId(account) || '',
    },

View on GitHub (pinned to 1ed8b77992)

Solutions

Re-run the OAuth flow to repopulate tokens.access_token
Verify the account's auth type classification before export
Skip accounts without access tokens in the export batch
Restore tokens via a quota/auth refresh that re-authenticates the account

Example fix

// before
const auth = toOfficialAuthJson(account); // throws
// after
if (account.tokens?.access_token?.trim()) {
  const auth = toOfficialAuthJson(account);
}

Defensive patterns

Strategy: validation

Validate before calling

if (!isCodexApiKeyAccount(account) && !account.tokens?.access_token?.trim()) {
  throw new Error('account missing access_token for auth.json');
}

Type guard

function isExportableAuthAccount(a: CodexAccount): boolean {
  return isCodexApiKeyAccount(a) ? !!a.openai_api_key?.trim() : !!a.tokens?.access_token?.trim();
}

Try / catch

try {
  const auth = toOfficialAuthJson(account);
} catch (e) {
  if ((e as Error).message === 'Official auth.json requires access_token') {
    // trigger re-auth or skip account
  }
}

Prevention

Re-authenticate accounts whose tokens are missing before export
Avoid clearing tokens on transient refresh failures
Pre-flight export batches for access_token presence

When it happens

Trigger: Calling toOfficialAuthJson on a non-API-key account where account.tokens?.access_token trims to empty — e.g. OAuth never completed, tokens cleared after failed refresh, or partially imported data.

Common situations: Interrupted OAuth login; token wiped by an auth failure; migration from an older storage format that lost the token field.

Related errors

AI-assisted analysis of jlcodes99/cockpit-tools@1ed8b77992 (2026-09-05). Data as JSON: /api/errors/838f245d22fc89c0. Report an issue: GitHub.