Troubleshooting Reddit 403 Errors with rdt-cli in Agent Reach

The 403 Forbidden error occurs when rdt-cli is installed but not authenticated; run rdt login or manually provide cookies in ~/.config/rdt-cli/credential.json to resolve the authentication gap detected in agent_reach/channels/reddit.py.

Agent Reach treats Reddit as a channel that can be accessed through two possible back-ends: OpenCLI (which re-uses a logged-in browser session) and rdt-cli (which works with a cookie file). When you encounter a 403 error using rdt-cli, the issue stems from Reddit rejecting unauthenticated requests, which the channel's check() method surfaces as a warning or error depending on the root cause.

How Agent Reach Detects Reddit Backend Status

The Backend Probe Order

The channel implementation in agent_reach/channels/reddit.py maintains an ordered_backends list that probes available back-ends sequentially. The check() method picks the first back-end reporting an ok or warn status, which is what the CLI and doctor command display to users.

Subprocess Detection Logic

When probing rdt-cli, the code uses shutil.which("rdt") to verify installation (lines 96-100). If found, it executes rdt status --json with a 10-second timeout (lines 115-119) and parses the output to determine authentication state.

Common Causes of 403 Errors with rdt-cli

Missing Installation

If shutil.which("rdt") returns None, the probe returns None for this backend, causing Agent Reach to skip it entirely. The recommended fix is installing from the pinned git source stored in _RDT_GIT_SOURCE (lines 22-33).

pipx install --force "git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66"

Broken Executable

When subprocess.run() raises OSError or returns exit codes 126/127, the probe returns an error with the _RDT_BROKEN_HINT message (lines 118-124). This typically occurs when the virtual environment disappears or the interpreter path becomes invalid.

Authentication Failure

The most common source of 403 errors occurs when rdt status --json executes successfully but returns "authenticated": false (lines 129-149). In this case, Reddit accepts the connection but rejects the request due to missing session cookies, triggering the warning status that advises login.

Parse Errors and Timeouts

If JSON decoding fails (lines 130-136), the probe falls back to a warn status indicating the output cannot be parsed. Network timeouts, often affecting users in Mainland China, raise TimeoutExpired after 10 seconds and yield an explicit error message advising proxy configuration.

Step-by-Step Resolution

1. Verify Backend Health

Run the diagnostic command to see the exact probe status:

agent-reach doctor reddit

Expect output indicating either rdt-cli 可用但未登录 (available but not logged in) or rdt-cli 可用 (已登录…) (available and authenticated).

2. Automatic Login

Execute the interactive login flow to extract cookies automatically:

rdt login

This opens a temporary browser, copies the reddit_session cookie, and writes it to the credential file, setting "authenticated": true for subsequent check() probes.

3. Manual Cookie Injection

If automatic login fails, manually create the credential file at ~/.config/rdt-cli/credential.json with the schema defined in the source comments (lines 60-66):

cat > ~/.config/rdt-cli/credential.json <<EOF
{
  "cookies": {
    "reddit_session": "<paste-value-from-Cookie-Editor>"
  },
  "source": "manual",
  "username": "<your-reddit-username>",
  "modhash": null,
  "saved_at": 0,
  "last_verified_at": null
}
EOF

4. Confirm Authentication

Verify the fix by checking the JSON output directly:

rdt status --json | jq .data.authenticated

This should output true. Once confirmed, Agent Reach will report the back-end as ok rather than warn.

5. Network Configuration for Restricted Regions

For users behind the Great Firewall, export proxy settings before running any Reddit commands:

export https_proxy=http://your-proxy:port
agent-reach read https://www.reddit.com/r/python/comments/example_post

Summary

• 403 errors indicate authentication gaps, not connection failures, when using rdt-cli with Agent Reach.
• The check() method in agent_reach/channels/reddit.py probes rdt status --json and parses the "authenticated" field to determine status.
• Install from git source using the _RDT_GIT_SOURCE URL to avoid broken executables detected via exit codes 126/127.
• Resolve 403s by running rdt login or manually writing cookies to ~/.config/rdt-cli/credential.json.
• Handle timeouts by ensuring network access and proxy configuration, particularly for the 10-second subprocess timeout in utf8_subprocess_env.

Frequently Asked Questions

Why does Agent Reach show rdt-cli as available but I still get 403 errors?

The check() method distinguishes between installation health and authentication state. If rdt is installed but returns "authenticated": false, the probe reports a warn status rather than error, allowing the channel to function but indicating that Reddit will reject requests with 403. Run rdt login to move from warn to ok status.

How do I fix a broken rdt-cli installation that shows exit code 126?

Exit code 126 indicates a permission problem or missing interpreter, while 127 indicates command not found. Both trigger the _RDT_BROKEN_HINT in lines 118-124 of agent_reach/channels/reddit.py. Reinstall using pipx install --force with the git URL from _RDT_GIT_SOURCE to restore the executable.

What should I do if rdt status --json returns invalid JSON?

If the probe cannot parse the output (lines 130-136), it falls back to a warning state. Run rdt status --json manually to inspect the raw output. If the format changed due to a version update, upgrade rdt-cli from the pinned git source to restore compatibility with the JSON parser in agent_reach/channels/reddit.py.

Where does Agent Reach look for rdt-cli credentials?

The channel expects credentials at ~/.config/rdt-cli/credential.json, as defined by the _CREDENTIAL_FILE constant (lines 20-23). The file must contain a JSON object with a cookies map including the reddit_session value, matching the schema documented in the source comments at lines 60-66.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}