CherryHQ/cherry-studio · error · Error

Failed to read OAuth storage: ${error instanceof Error ? err

Error message

Failed to read OAuth storage: ${error instanceof Error ? error.message : String(error)}

What it means

Thrown by `readStorage()` in the OAuth JSON file storage when reading or parsing the OAuth state file fails with an error other than ENOENT (file-not-found, which is handled gracefully by creating initial state). The file is expected to be valid JSON conforming to OAuthStorageSchema; corruption, schema mismatch, or permission errors trigger this.

Source

Thrown at src/main/ai/mcp/oauth/storage.ts:45

    if (this.cache) {
      return this.cache
    }

    try {
      const data = await fs.readFile(this.filePath, 'utf-8')
      const parsed = JSON.parse(data)
      const validated = OAuthStorageSchema.parse(parsed)
      this.cache = validated
      return validated
    } catch (error) {
      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
        // File doesn't exist, return initial state
        const initial: OAuthStorageData = { lastUpdated: Date.now() }
        await this.writeStorage(initial)
        return initial
      }
      logger.error('Error reading OAuth storage:', error as Error)
      throw new Error(`Failed to read OAuth storage: ${error instanceof Error ? error.message : String(error)}`)
    }
  }

  private async writeStorage(data: OAuthStorageData): Promise<void> {
    try {
      // Ensure directory exists
      await fs.mkdir(path.dirname(this.filePath), { recursive: true })

      // Update timestamp
      data.lastUpdated = Date.now()

      // Write file atomically
      const tempPath = `${this.filePath}.tmp`
      await fs.writeFile(tempPath, JSON.stringify(data, null, 2))
      await fs.rename(tempPath, this.filePath)

      // Update cache
      this.cache = data

View on GitHub (pinned to 726446b54c)

Solutions

Delete or rename the corrupted OAuth JSON file (located in the MCP config directory as `{hash}_oauth.json`) — the runtime will recreate it with initial state on next read
Check file permissions — the Electron app process must have read access
If schema migration is needed, clear all OAuth files and re-authenticate
On Windows, check if antivirus or another process is locking the file

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const tokens = await oauthStorage.getTokens()
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to read OAuth storage')) {
    // File is corrupted — delete it so next read recreates initial state
    await fs.unlink(oauthFilePath).catch(() => {})
    // Restart OAuth flow from scratch
    return restartOAuthFlow()
  }
  throw e
}

Prevention

Never manually edit OAuth JSON files
Handle read failures by deleting the corrupted file and re-authenticating
Monitor disk health — recurring storage corruption may indicate hardware failure

When it happens

Trigger: The OAuth JSON file (`{serverUrlHash}_oauth.json`) exists but contains invalid JSON, fails Zod schema validation (OAuthStorageSchema.parse), has a permission issue preventing read access, or experiences a disk I/O error.

Common situations: File was partially written (crash during write — the atomic rename should prevent this but a hard crash could leave .tmp); file was manually edited and corrupted; file permissions changed; schema changed in an app update and old files don't validate; antivirus locking the file on Windows.

Related errors

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/3f138bde436a136a. Report an issue: GitHub.