Troubleshooting and compatibility
The database is not ready
Section titled “The database is not ready”Check GET /v1/status. Grant iMessage Relay, or the terminal running the
standalone server, Full Disk Access in System Settings > Privacy & Security.
Reload the app configuration or restart the standalone process. If you set
RELAY_CHAT_DB_PATH, check that it points to the intended Messages database.
Sending is denied
Section titled “Sending is denied”Sending is disabled until the app’s allowedRecipients setting or the CLI’s
RELAY_ALLOWED_RECIPIENTS variable contains recipients. An empty allowlist
denies every send. For an existing group chat, every participant must be allowed.
If a stored participant cannot be identified, the relay refuses the send with
503 database_unavailable instead of checking an incomplete participant list.
Set the app’s senderAccountID or the CLI’s RELAY_SENDER_ACCOUNT_ID for direct
sends. The value identifies your local iMessage account, not the recipient. A
conversation send uses the account context stored in chat.db.
The first send can prompt for Automation > Messages permission. Neither
/v1/status nor /v1/sender triggers this prompt. Both routes report the sender
capability as permission_unknown without probing Messages.
Attachment sends use Accessibility and require an existing conversation. Grant
Accessibility permission to the process that runs imessage-relay. Direct media
sends to to are unsupported.
See send errors before retrying. A 502 response
with send_result_unknown, or a request status of result_unknown after an
interruption, means the outcome is uncertain. Poll the original request_id to
check for a matching provider message. Do not retry with a new idempotency key.
A native reply is unavailable
Section titled “A native reply is unavailable”The public Messages AppleScript dictionary does not expose native replies. The
relay uses Accessibility instead. Grant Accessibility permission to the relay
process and send through an existing conversation_id.
A saved cursor stops working
Section titled “A saved cursor stops working”Start again without the cursor after a 400 response. See pagination for query binding and database fingerprint rules.
Some messages have empty text
Section titled “Some messages have empty text”Some messages have no text, such as attachment-only messages. For legacy
attributed bodies, the relay decodes the archived attributed string when
possible. Unknown or undecodable content remains null.
macOS compatibility
Section titled “macOS compatibility”The app and standalone binary require macOS 14 or newer. GitHub release artifacts carry a Developer ID signature, and Apple notarizes both executables. The app also carries a stapled notarization ticket. Local packages use ad hoc signing and are not notarized.
The Messages database has a private schema that changes between macOS releases. The relay is tested on macOS 27. Other versions may require changes.