Troubleshooting

Both login paths below fail on current KakaoTalk macOS builds. login --save can't find a token in the cache, and login --manual hits status=-100 with no working device-registration endpoint. Do not repeatedly retry --manual — it can get your account's sub-device login blocked (#20, #22). local-send/ax-read don't need login at all.

login --save works by reading the KakaoTalk macOS app's HTTP cache (Cache.db) and pulling the Authorization header out of cached REST responses. Recent KakaoTalk macOS builds have changed how they cache responses — authenticated REST calls are no longer written to NSURLCache. On those builds:

Cache.db still exists, is readable, and contains entries — but zero entries with an Authorization header.
v1.2.2+ detects this and prints a dedicated message pointing at issue #15.
"Open the app and click a chat" does not help on these builds — the request never reaches Cache.db regardless of activity.

If you see the "contains zero entries with an Authorization header" message, there is currently no working recovery: login --manual (the former fallback) is also broken on these builds — see the Manual login section below. This is tracked in #15.

The login command reads credentials out of the KakaoTalk macOS app's HTTP cache. If it cannot find any auth requests, it prints which condition failed. Walk through the three checks below in order:

1. KakaoTalk has emitted at least one authenticated REST request

Open the KakaoTalk macOS app, sign in, and click a chat or refresh the friend list at least once. Just leaving the app on the main window is sometimes not enough — the cache is populated by REST calls, not by the app being open.

2. Cache.db actually exists

ls -lh ~/Library/Containers/com.kakao.KakaoTalkMac/Data/Library/Caches/Cache.db

If the file is missing, the app has never run on this user account (or the OS recently cleared the cache). Open KakaoTalk and trigger a REST call as in step 1.

3. Your terminal has Full Disk Access

~/Library/Containers/com.kakao.KakaoTalkMac/... lives in macOS's sandbox-protected area. Confirm:

cat ~/Library/Containers/com.kakao.KakaoTalkMac/Data/Library/Caches/Cache.db > /dev/null

If you get a permission error, add your terminal (Terminal.app, iTerm2, WezTerm, etc.) to System Settings → Privacy & Security → Full Disk Access and then fully quit and relaunch the terminal.

Once all three checks pass, retry:

openkakao-cli login --save
openkakao-cli doctor

For verbose output during the scan:

OPENKAKAO_CLI_DEBUG=1 openkakao-cli login --save

login --manual logs in directly with your KakaoTalk email/phone and password, deriving the device UUID from the Mac's IOPlatformUUID and computing the X-VC header locally:

openkakao-cli login --manual --save

This no longer completes on current KakaoTalk builds

On recent KakaoTalk macOS builds, logging in from a device the account has not seen before makes login.json return status=-100 (device not registered). The official app once exposed a passcode/register_device step to clear this, but those REST endpoints no longer exist on macOS (they return HTTP 404, confirmed via binary analysis in #22). v1.3.2 tried to automate the passcode flow; it could not work and was reverted in v1.3.3.

🚨 Do not keep retrying. Repeated logins from an unregistered device have gotten real users' accounts' sub-device login blocked (#20). There is no known workaround for server login — but you don't need one: use local-send/ax-read, which drive the KakaoTalk UI directly and never authenticate to Kakao's servers.

Writing `credentials.json` by hand

If you already have a token through another channel, you can write ~/.config/openkakao/credentials.json directly instead:

{
  "oauth_token": "<Authorization header value>",
  "user_id": 1234567890,
  "device_uuid": "<suffix after the first '-' of the token>",
  "app_version": "3.7.0",
  "user_agent": "",
  "a_header": ""
}

Then openkakao-cli auth to verify. For unattended relogin, set auth.password_cmd (and optionally auth.email_cmd) in ~/.config/openkakao/config.toml so the password is fetched from a secret manager instead of being stored.

Token expired or commands start returning auth errors

Try:

openkakao-cli relogin --fresh-xvc
openkakao-cli auth

If refresh logic used to work and now does not, assume upstream behavior may have changed.

`watch` reconnects repeatedly

Typical causes:

unstable network path
stale auth state
server reassignment
a workflow that never exits on permanent auth failure

Start narrower:

openkakao-cli watch --max-reconnect 0

This makes failures easier to see without an endless loop hiding the root cause.

Sending works inconsistently

Check whether you are:

sending to an open chat
retrying too aggressively
relying on stale chat identifiers
mixing read-only assumptions with outbound jobs

Media download or upload breaks

Validate that the affected command still works on a small manual case before putting it back into automation. Media flows are often more fragile than plain text operations.

LOCO Protocol Error Codes

When a LOCO command fails, the server returns a numeric status code. These are the most common:

Code	Meaning	What to do
`0`	Success	Nothing to fix
`-950`	Token expired or wrong token type	Your access token has expired. Run `openkakao-cli relogin --fresh-xvc` to get a fresh token. If you are using a Cache.db REST token (~138 chars) for LOCO commands, that will not work -- LOCO requires the login.json access_token (~65 chars).
`-300`	Device or request mismatch	The device_uuid or userId does not match what the server expects. Verify your local app state matches the logged-in session. Re-run `login --save` to re-extract identifiers.
`-203`	Missing required parameter	The LOCO method exists, but the request body is incomplete. A required BSON field is missing. Re-run `login --save` and check that `credentials.json` has all expected fields.
`-400`	Missing parameters	A required BSON field is missing from the request. This usually means the local credential extraction is incomplete. Re-run `login --save` and check that `credentials.json` has all expected fields.
`-999`	Upgrade required	The app version string is too old. Update KakaoTalk and re-extract credentials with `login --save`.

Enable debug logging for more detail:

OPENKAKAO_CLI_DEBUG=1 openkakao-cli read <chat_id>

The previous variable name OPENKAKAO_RS_DEBUG=1 is still recognized for backward compatibility.

This prints raw LOCO packet exchanges, which helps identify exactly which command is failing and what the server returned.

Good debugging posture

reduce the command to the smallest failing case
verify auth separately from messaging
prefer one-shot commands before watch loops
keep shell output and command history available while reproducing

Troubleshooting

On this page