Troubleshooting

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

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