tinyhumansai/openhuman · error · anyhow::Error

open chat.db failed ({}). Grant Full Disk Access to OpenHuma

Error message

open chat.db failed ({}). Grant Full Disk Access to OpenHuman: System Settings → Privacy & Security → Full Disk Access.

What it means

Opening ~/Library/Messages/chat.db read-only (SQLITE_OPEN_READ_ONLY | SQLITE_OPEN_PRIVATE_CACHE) failed; on macOS the overwhelmingly common cause is TCC denying the app Full Disk Access, so the error embeds the exact remediation path alongside the raw rusqlite error (unable to open database file / SQLITE_CANTOPEN).

Source

Thrown at app/src-tauri/src/imessage_scanner/chatdb.rs:48

    pub chat_name: Option<String>,
    pub service: Option<String>,
}

/// Open chat.db read-only. Returns a friendly error hint if Full Disk
/// Access is not granted (the typical failure mode on first run).
fn open(db_path: &Path) -> rusqlite::Result<Connection> {
    Connection::open_with_flags(
        db_path,
        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_PRIVATE_CACHE,
    )
}

/// Read up to `limit` messages with `ROWID > since_rowid`, ordered by
/// ROWID ascending. Joins across message / handle / chat_message_join /
/// chat to produce one flat record per message.
pub fn read_since(db_path: &Path, since_rowid: i64, limit: usize) -> anyhow::Result<Vec<Message>> {
    let conn = open(db_path).map_err(|e| {
        anyhow::anyhow!(
            "open chat.db failed ({}). Grant Full Disk Access to OpenHuman: \
             System Settings → Privacy & Security → Full Disk Access.",
            e
        )
    })?;

    let mut stmt = conn.prepare(
        r#"
        SELECT
          m.ROWID            AS rowid,
          m.guid             AS guid,
          m.text             AS text,
          m.attributedBody   AS attributed_body,
          m.date             AS date_ns,
          m.is_from_me       AS is_from_me,
          h.id               AS handle_id,
          c.chat_identifier  AS chat_identifier,
          c.display_name     AS chat_name,

View on GitHub (pinned to a221052e0d)

Solutions

  1. Grant Full Disk Access to the exact app/binary that runs the scanner: System Settings → Privacy & Security → Full Disk Access → add/enable OpenHuman
  2. Fully quit and restart the app afterwards — TCC is checked at open time, not retroactively
  3. Confirm the db exists: ls -l ~/Library/Messages/chat.db; if missing, open Messages.app once so macOS creates/syncs it

Example fix

# before — scanner logs: open chat.db failed (unable to open database file). Grant Full Disk Access...
# after — verify from the same user context, then restart the app
 sqlite3 "file:$HOME/Library/Messages/chat.db?mode=ro" 'select count(*) from message;'
# a number ⇒ readable; an error ⇒ FDA still missing for that context
Defensive patterns

Strategy: validation

Validate before calling

// preflight before scheduling the macOS scanner
let db = std::path::Path::new(&home).join("Library/Messages/chat.db");
if !db.exists() { return Ok(None); }  // nothing to scan
match std::fs::metadata(&db) {
    Ok(_) => {}
    Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
        log::warn!("[imessage] chat.db unreadable — prompt for Full Disk Access");
        return Ok(None);
    }
    Err(e) => return Err(anyhow::anyhow!("stat chat.db failed: {e}")),
}

Try / catch

match chatdb::read_since(&db, since, limit) {
    Ok(msgs) => Ok(msgs),
    Err(e) if e.to_string().contains("open chat.db failed") => {
        log::warn!("[imessage] chat.db unopenable ({e}) — likely FDA; disabling until granted");
        Ok(Vec::new())
    }
    Err(e) => Err(e),
}

Prevention

When it happens

Trigger: The process reading the db lacks Full Disk Access so macOS TCC denies open(2) on ~/Library/Messages/chat.db; alternatively the file is absent or relocated (fresh macOS profile, Messages-in-iCloud not yet synced down, OS upgrade).

Common situations: First scan after install before FDA was granted; FDA granted to a different binary than the one opening the db (launcher vs bundled helper); macOS re-evaluation of TCC identity after an app update; user revoked FDA later.

Related errors

AI-assisted analysis of tinyhumansai/openhuman@a221052e0d (2026-08-16). Data as JSON: /api/errors/d95cfe58e166aac6. Report an issue: GitHub.