zeroclaw-labs/zeroclaw · error · anyhow::Error

Messages database not found at {}. Ensure Messages.app is se

Error message

Messages database not found at {}. Ensure Messages.app is set up and Full Disk Access is granted.

What it means

IMessageChannel::listen polls ~/Library/Messages/chat.db (built from the user's home dir) for inbound messages; before opening the SQLite connection it checks db_path.exists() and bails with this message when the chat database is not there. On modern macOS the chat.db is protected by TCC, so the practical causes are: Messages.app never initialized the database, or the calling process lacks Full Disk Access so the path is not even visible.

Source

Thrown at crates/zeroclaw-channels/src/imessage.rs:208

            "iMessage channel listening (AppleScript bridge)..."
        );

        // Query the Messages SQLite database for new messages
        // The database is at ~/Library/Messages/chat.db
        let db_path = UserDirs::new()
            .map(|u| u.home_dir().join("Library/Messages/chat.db"))
            .ok_or_else(|| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure),
                    "Cannot find home directory"
                );
                anyhow::Error::msg("Cannot find home directory")
            })?;

        if !db_path.exists() {
            anyhow::bail!(
                "Messages database not found at {}. Ensure Messages.app is set up and Full Disk Access is granted.",
                db_path.display()
            );
        }

        // Open a persistent read-only connection instead of creating
        // a new one on every 3-second poll cycle.
        let path = db_path.to_path_buf();
        let conn = tokio::task::spawn_blocking(move || -> anyhow::Result<Connection> {
            Ok(Connection::open_with_flags(
                &path,
                OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
            )?)
        })
        .await??;

        // Track the last ROWID we've seen (shuttle conn in and out)
        let (mut conn, initial_rowid) =

View on GitHub (pinned to 88bb9c8533)

Solutions

Verify the file exists: ls ~/Library/Messages/chat.db — if missing, open Messages.app once and sign in so it creates the database
Grant Full Disk Access to the app that runs zeroclaw (terminal, launchd agent, or the binary itself) under System Settings > Privacy & Security > Full Disk Access, then restart that app
Confirm HOME/user-dirs resolution points at the interactive user's home when running under a service account
Re-run listen() after granting permissions — TCC changes require restarting the granted process

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight before listen():
let db = home.join("Library/Messages/chat.db");
anyhow::ensure!(
    db.exists(),
    "~/Library/Messages/chat.db missing: open Messages.app once and grant Full Disk Access"
);

Try / catch

if let Err(e) = channel.listen(tx).await {
    if e.to_string().contains("Messages database not found") {
        // environment problem: prompt operator for Full Disk Access / Messages.app setup, then restart
    }
}

Prevention

Grant Full Disk Access to whatever app launches zeroclaw (terminal, launchd agent) before enabling the imessage channel
Open Messages.app and sign in once on any fresh Mac before using this channel
Re-check permissions after macOS upgrades — TCC grants sometimes reset

When it happens

Trigger: listen() is called on a Mac where ~/Library/Messages/chat.db does not exist or is invisible to the process: fresh macOS install where Messages.app was never set up, a different user's home (UserDirs resolving elsewhere), or TCC denying Full Disk Access to the binary/terminal running zeroclaw.

Common situations: Headless Mac mini / CI runner where Messages.app was never opened; zeroclaw started from a launchd agent or IDE whose parent app lacks Full Disk Access; macOS upgrade re-prompting TCC consent.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/8aedd948863829eb. Report an issue: GitHub.